{"id":10508,"library":"api-elements","title":"API Elements JavaScript Library","description":"The `api-elements` package provides a JavaScript interface for working with API Elements, an abstract syntax tree (AST) for describing APIs. It acts as a core component within the larger API Elements ecosystem, enabling programmatic creation, manipulation, and serialization of API descriptions using a unified model, regardless of the original format (like OpenAPI or API Blueprint). The current stable version of this specific package is 0.3.2, though its sub-packages, like `@apielements/openapi3-parser` and `@apielements/openapi2-parser`, are more actively developed with frequent minor and patch releases, incorporating new OpenAPI specification features and bug fixes. This library differentiates itself by offering a language-agnostic, structured representation of API definitions, allowing for advanced tooling and transformations beyond simple parsing.","status":"active","version":"0.3.2","language":"javascript","source_language":"en","source_url":"https://github.com/apiaryio/api-elements.js","tags":["javascript"],"install":[{"cmd":"npm install api-elements","lang":"bash","label":"npm"},{"cmd":"yarn add api-elements","lang":"bash","label":"yarn"},{"cmd":"pnpm add api-elements","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While the README shows `const apiElements = require('api-elements'); const namespace = new apiElements.Namespace();`, the `Namespace` class is the primary construct. For ESM, direct named import is expected.","wrong":"const { Namespace } = require('api-elements');","symbol":"Namespace","correct":"import { Namespace } from 'api-elements';"},{"note":"This is the primary CommonJS import pattern, returning an object containing the Namespace class and potentially other utilities.","symbol":"apiElements","correct":"const apiElements = require('api-elements');"},{"note":"Elements like `ParseResult` are typically accessed via `namespace.elements.ParseResult`. Direct importing from a subpath might be necessary for tree-shaking or specific element access in ESM.","wrong":"import { ParseResult } from 'api-elements';","symbol":"ParseResult","correct":"import { ParseResult } from 'api-elements/lib/elements';"}],"quickstart":{"code":"const apiElements = require('api-elements');\nconst namespace = new apiElements.Namespace();\n\n// Parsing a JSON Representation of an API Elements tree\nconst parseResult = namespace.serialiser.deserialise({\n  element: 'parseResult',\n  content: [\n    {\n      element: 'category',\n      meta: { classes: ['api'] },\n      content: [\n        { element: 'copy', content: 'My Awesome API' },\n        { element: 'resource', content: [] }\n      ]\n    }\n  ]\n});\n\nconsole.log('Deserialized ParseResult element:', parseResult.element);\nconsole.log('API title:', parseResult.api.copy.toValue());\n\n// Creating API Elements directly\nconst directParseResult = new namespace.elements.ParseResult();\nconst apiCategory = new namespace.elements.Category();\napiCategory.classes.push('api');\napiCategory.content.push(new namespace.elements.Copy('Another API'));\ndirectParseResult.content.push(apiCategory);\n\nconsole.log('Directly created ParseResult element:', directParseResult.element);\nconsole.log('Another API title:', directParseResult.api.copy.toValue());","lang":"javascript","description":"This quickstart demonstrates how to initialize the API Elements namespace and create or deserialize API Element ASTs. It shows both parsing a JSON representation and constructing elements programmatically, then accessing properties like the API title."},"warnings":[{"fix":"Refer to the `api-elements.js` GitHub repository for the latest API documentation and examples. Consider pinning to exact patch versions if stability is critical.","message":"The `api-elements` package itself has a relatively low version (0.3.x) which can imply a less stable API compared to 1.0+ packages. While its underlying parsers are more active, direct usage of `api-elements` might involve more frequent adjustments.","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Ensure your OpenAPI 2.0 definitions explicitly define the `schemes` property (e.g., `schemes: [\"http\"]` or `schemes: [\"https\"]`) to control the generated host URI, or update your application logic to expect `https` by default for missing schemes.","message":"When consuming `Host URI metadata` from `openapi2-parser`, the default scheme changed from potentially undefined to `https` if `schemes` is not explicitly defined in the OpenAPI 2.0 specification. This might affect applications relying on an `http` default or a partial URI.","severity":"breaking","affected_versions":"<0.32.4"},{"fix":"Upgrade to `@apielements/openapi2-parser@0.32.6` or newer to ensure correct generation of example JSON bodies from Swagger/OpenAPI 2.0 schemas with complex internal references.","message":"Handling references to JSON paths that prefix the current path (e.g., `$ref: '#/definitions/User'` from a path inside `UserList`) was buggy in `openapi2-parser` when generating example JSON bodies. This could lead to incorrect or incomplete examples.","severity":"gotcha","affected_versions":"<0.32.6"},{"fix":"Be aware of emitted 'unsupported warnings' when parsing OpenAPI 3.1 definitions. Test your specific 3.1 features with the parser and check its release notes for ongoing support and limitations. Provide feedback to the maintainers for missing features.","message":"Support for OpenAPI 3.1 features in `@apielements/openapi3-parser` is progressive. While basic `const` and array `type` support for 'Schema Object' is present, not all OpenAPI 3.1 features and fields are fully supported and may emit warnings.","severity":"gotcha","affected_versions":">=0.16.0"},{"fix":"Update the `api-elements` package to at least `0.3.1` to benefit from fixes in value generation logic, and ensure `apib-serializer` is at `0.16.3` or newer for correct header handling.","message":"Older versions of `api-elements` might have unexpected behavior when generating values from elements, especially for objects with only undefined property values, or when handling headers without explicit values. These have been addressed in recent patches.","severity":"deprecated","affected_versions":"<0.3.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Always check for the existence of intermediate elements (e.g., `if (parseResult.api && parseResult.api.copy)`) before attempting to access their properties, especially when dealing with potentially incomplete or malformed API descriptions.","cause":"Attempting to access properties like `parseResult.api.copy` when `parseResult.api` is `null` or `undefined`, usually because the parsed API description lacks a main API category or a copy element within it.","error":"TypeError: Cannot read properties of undefined (reading 'copy')"},{"fix":"Ensure that any arguments passed to API Elements functions or methods are instances of `namespace.elements.SomeElement` or other valid Refract elements. Convert plain data structures into appropriate `minim` or `api-elements` element types before use.","cause":"This error typically occurs when a function expecting an API Element (part of the Refract AST) receives a plain JavaScript object or a primitive value instead.","error":"Error: Not a Refract element: <value>"},{"fix":"Verify that the JSON string passed to `namespace.serialiser.deserialise` is valid, complete, and represents a proper API Elements structure. Use a JSON linter or validator to check the input.","cause":"When deserializing API Elements from a JSON string, this error indicates that the input JSON is malformed or empty, preventing the serializer from correctly processing it.","error":"JSON.parse: unexpected end of data at line 1 column 1 of the JSON data"}],"ecosystem":"npm"}