A node web server that runs on Koa that provides an API to parse an API using the AMF parser.
npm i @api-components/amf-web-apiimportServerfrom'@api-components/amf-web-api';(async()=>{consthttpPort=8080;constsslPort=8081;constsslOptions={key: fs.readFileSync('key.pem'),cert: fs.readFileSync('cert.pem')};constsrv=newServer();srv.setupRoutes('/api/v1');// optional prefix for the API routes.awaitsrv.startHttp(httpPort);awaitsrv.startSsl(sslOptions,httpPort);// when ready...awaitsrv.stopHttp();awaitsrv.stopSsl();})();See the API spec in spec/ folder for more details.
Notes:
- Examples assume no API prefix and port 8080
- Example responses are formatted for readability
This endpoint creates a task to parse the content. It does not wait for the parsing result. Instead it returns the location of the endpoint to query for the parsing result.
The x-api-vendor is required and it is the API vendor to use. It is one of the API vendors supported by the AMF parser: RAML 0.8, RAML 1.0, OAS 2.0, OAS 3.0, and ASYNC 2.0.
The content type is optional and is ignored by the server. However, it is a good practice to keep it and set the correct value.
POST /text HTTP/1.1Host: localhost:8080Content-Type: application/ramlx-api-vendor: RAML 1.0content-length: 147#%RAML 1.0title: Demo APIversion: v2baseUri: https://api.mulesoft.com/{version}mediaType: application/jsonprotocols: [HTTPS]HTTP/1.1 201 Createdlocation: /job/64d7ed3c-d598-479c-920b-9d19ed002917Content-Type: application/json; charset=utf-8Content-Length: 121Date: Sat, 06 Nov 2021 00:01:15 GMTConnection: keep-aliveKeep-Alive: timeout=5
{
"status": 201,
"location": "/job/64d7ed3c-d598-479c-920b-9d19ed002917",
"key":"64d7ed3c-d598-479c-920b-9d19ed002917"
}To parse an entire API project with multiple files send a zip file in the request body.
You can set an optional x-entrypoint header with the name of the API's main file (the entry point). When the header is not set then the server application tries to determine the best candidate using some built-in heuristics.
When multiple entrypoints are found in the project then the job status endpoint returns the list of files with the 300 status code. The client should pick one (probably involving the user). After the pick is ready the client sends the PUT request to the job status endpoint (see below).
When a single endpoint is found in the API project then it is used automatically as the entrypoint. When no files are found then the process ends with an error.
POST /file HTTP/1.1Host: localhost:8080Content-Type: application/zipcontent-length: 3576[binary content]HTTP/1.1 201 Createdlocation: /job/c04401ec-eccd-45e7-b004-0d2884be6d5cContent-Type: application/json; charset=utf-8Content-Length: 121Date: Sat, 06 Nov 2021 00:01:15 GMTConnection: keep-aliveKeep-Alive: timeout=5
{
"status": 201,
"location": "/job/c04401ec-eccd-45e7-b004-0d2884be6d5c",
"key":"c04401ec-eccd-45e7-b004-0d2884be6d5c"
}The request:
GET /job/c04401ec-eccd-45e7-b004-0d2884be6d5c HTTP/1.1Host: localhost:8080When the parsing result is ready the response returns the ld+json model generated by the AMF library. After that the process is removed from the server and it is impossible to read the value again.
The response:
HTTP/1.1 200 OKContent-Type: application/ld+jsonContent-Length: 86868Date: Sat, 06 Nov 2021 00:04:47 GMT
{
"@graph": [
{
"@id": "#37",
"@type": [
"doc:APIContractProcessingData"
],
"apiContract:modelVersion": "3.2.0",
"doc:transformed": true,
"doc:sourceSpec": "OAS 2.0"
},
{
"@id": "#38",
"@type": [
"apiContract:WebAPI",
"apiContract:API",
"doc:RootDomainElement",
"doc:DomainElement"
],
"core:name": "Swagger Petstore",
"core:description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification",
"apiContract:server": [
....This response is returned when the parser is still running. This may happen in case of a very complex API. In this case the client should wait and try again. Note, too many requests may cause the server to refuse serving the content. It will return the 429 and 425 status codes respectively. See the RAML spec for the details.
HTTP/1.1 204 OKlocation: /job/c04401ec-eccd-45e7-b004-0d2884be6d5cDate: Sat, 06 Nov 2021 00:04:47 GMTThis happens when parsing a zip file. When the application cannot determine the entry point to the API spec file and the x-entrypoint header was not set on the request then the response contains the list of potential candidates that the client (and possibly the user) should choose from.
HTTP/1.1 300 Multiple ChoicesContent-Type: application/jsonContent-Length: 125Date: Sat, 06 Nov 2021 00:04:47 GMT
{
"files": [
"my-api.raml",
"other.json"
]
}The files returned this way have an API header (RAML, swagger, OAS, Async) and all can be used as an entry point. When the client choose the entrypoint then it should send the PUT request to the same endpoint. See below for details.
The easiest way is to set the x-entrypoint header on the /files request. However, it is not always possible or desired. In this case the status endpoint returns the list of entrypoints it thinks is to be the best matches for an endpoint. Once picked, send the entrypoint name in the PUT request to the job status.
PUT /job/c04401ec-eccd-45e7-b004-0d2884be6d5c HTTP/1.1Host: localhost:8080Content-Type: application/jsoncontent-length: 28
{
"entrypoint": "my-api.raml"
}This will result with the same response as with the /file endpoint.
When the client is sure that the result won't be read it should send the DELETE request to the job status endpoint to delete processing of the API and cleanup the resources.
Note, the parser process has a timeout after which it is automatically cleaned from memory when not used.
git clone https://github.com/api-components/amf-web-api
cd amf-web-api
npm installnpm testNote, Firefox is temporarily removed from tests until Playwright update FF version to at least 91.
This library has been created by Pawel Uchida-Psztyc on his own free time. It is licensed under Apache 2 license.