Skip to content

Parsing API project

Introduction

API Console works with a JSON-LD (which means JSON for Linking Data) model generated by the AMF parser. The model is a representation of a graph generated from the API project.

At the moment AMF (and therefore API Console) can read the following API formats:

  • RAML 0.8
  • RAML 1.0
  • OAS 2.0
  • OAS 3.0

Heads up

OAS 3.0 support is in experimental phase and some language features may not be available at the moment. Feel free to open an issue report if you notice missing information.

Using the parser in your project

Info

This section assumes you have Node installed on you machine and you have basic knowledge about JavaScript programming.

First, install parser as a dependency of your project.

npm install --save amf-client-js

Then, import the parser in your code:

import amf from 'amf-client-js';

or Node's require

const amf = require('amf-client-js');

In the next step initialize the library:

amf.plugins.document.WebApi.register();
amf.plugins.document.Vocabularies.register();
amf.plugins.features.AMFValidation.register();

await amf.Core.init();

At this point the parser is ready to work.

Processing API project

Parsing the API

To parse the API project we need the following:

  • path to the API main file in format file://FILE_LOCATION or valid HTTP location to the API file
  • API type, for example RAML 1.0
  • API specification media type, like application/raml, application/yaml, or application/json
const type = 'RAML 1.0';
const parser = amf.Core.parser(type, 'application/raml');
const doc = await parser.parseFileAsync('file://./api.raml');

The first argument of the Core.parser() function is the API type. This is one of the supported API formats listed at the beginning of this document. Second argument is the media type of the API. For RAML files it's always application/raml. However, Open API Specification comes with two flavours: application/yaml and application/json.

The argument of parseFileAsync() is the location of the file to parse. It has to be a complete file location, including scheme. For local files use file:// scheme. Relative paths are accepted. You can also pass a HTTP link to the API specification file.

Validating the API

It may seems to be unnecessary step but it may save you a lot of time if something is wrong with the API project. AMF will try to read as much as it can, even when the API is invalid. The invalid sections will be ignored. To avoid debugging and searching for solutions on StackOverflow, always validate the API.

let validationProfile;
switch (type) {
  case 'RAML 1.0': validationProfile = amf.ProfileNames.RAML; break;
  case 'RAML 0.8': validationProfile = amf.ProfileNames.RAML08; break;
  case 'OAS 2.0':
  case 'OAS 3.0':
    validationProfile = amf.ProfileNames.OAS;
    break;
}
const result = await amf.AMF.validate(doc, validationProfile);
console.log(result.toString());

The type in the code snippet above is the same type as the first argument of calling amf.Core.parser() function. The AMF.validate() function takes the parsed document as the first argument and one of the validation profiles included info AMF library, under amf.ProfileNames property.

Finally you can just print the validation result to the console to see warning/error messages, if any.

Generating graph model

API Console uses something we call a resolved model. A resolved model is the same graph model but RAML types are resolved to a canonical model. This means that if a type inherits from other types, it's all resolved to a final shape of an object.

For this we are using a resolver for the "editing" pipeline. This is a special case created for API Console to generate the model it needs.

const resolver = amf.Core.resolver(type);
const resolvedDoc = resolver.resolve(doc, 'editing');

As the last step, generate the model, as string, from the graph.

const generator = amf.Core.generator('AMF Graph', 'application/ld+json');
const opts = amf.render.RenderOptions().withSourceMaps.withCompactUris;
const model = await generator.generateString(resolvedDoc, opts);

The model property has the AMF model the API Console can consume. You should store it somehow and then pass it to the console, when needed.