protagonist

Protagonist - API Blueprint Parser for Node.js

Protagonist is a Node.js wrapper for the Drafter, an API Blueprint parser. API Blueprint is a language for describing web APIs.

Install

NOTE: For general use we recommend that you use the Drafter NPM package instead of Protagonist directly as Protagonist needs to be compiled which may not be possible in every situation.

Protagonist can be installed via the Protagonist npm package by npm or yarn.

$ npm install protagonist
# or
$ yarn install protagonist

Protagonist uses the node-gyp build tool which requires Python 2.7 (3.x is not supported) along with a compiler and other build tools. Take a look at their installation steps for Linux, macOS, and Windows.

Usage

Protagonist offers the ability to both validate, and parse an API Blueprint. It offers the following APIs:

• validate(source, options)
• validateSync(source, options)
• parse(source, options)
• parseSync(source, options)

NOTE: It is not recommended to use the synchronous APIs as they can block the Node.JS event loop.

Validating an API Blueprint

You can validate an API Blueprint to determine if the source is a valid document. The parse result will contain any errors or warnings that the document would emit during parsing.

const protagonist = require('protagonist');

const parseResult = await protagonist.parse('# My API');
console.log(JSON.stringify(parseResult, null, 2));

or by using Promises:

const protagonist = require('protagonist');

protagonist.validate('# My API')
  .then((parseResult) => {
    console.log(JSON.stringify(parseResult, null, 2));
  })
  .catch((error) => {
    console.error(error);
  });

See the parse result section below for more information about the structure of the parse result.

Synchronous API

const protagonist = require('protagonist');
const parseResult = protagonist.validateSync('# My API');

Validation Options

Options can be passed to the parser as an optional second argument to both the asynchronous and synchronous interfaces:

const protagonist = require('protagonist');

const options = {
  requireBlueprintName: true,
};
const parseResult = await protagonist.validate('# My API', options);

The available options are:

Name	Description
requireBlueprintName	Require parsed blueprints have a title (default: false)

Parsing an API Blueprint

You can parse an API Blueprint with async/await:

const protagonist = require('protagonist');

const parseResult = await protagonist.parse('# My API');
console.log(JSON.stringify(parseResult, null, 2));

or by using Promises:

const protagonist = require('protagonist');

protagonist.parse('# My API')
  .then((parseResult) => {
    console.log(JSON.stringify(parseResult, null, 2));
  })
  .catch((error) => {
    console.error(error);
  });

See the parse result section below for more information about the structure of the parse result.

Synchronous API

const parseResult = protagonist.parseSync('# My API');

Parsing Options

Options can be passed to the parser as an optional second argument to both the asynchronous and synchronous interfaces:

const options = {
  generateSourceMap: true,
};
const parseResult = await protagonist.parse('# My API', options);

The available options are:

Name	Description
requireBlueprintName	Require parsed blueprints have a title (default: false)
generateSourceMap	Enable sourcemap generation (default: false)

Parse Result

The format of the parse result is an API Elements structure, there is also API Elements: JS which contains tooling to handle this format in JavaScript. It is recommended to use the provided API Elements tooling to prevent any tight coupling between your tool and a parse result.

As an example, parsing the following API Blueprint:

# GET /
+ Response 204

Would result in the following API Elements Parse Result:

{
  "element": "parseResult",
  "content": [
    {
      "element": "category",
      "meta": {
        "classes": {
          "element": "array",
          "content": [
            {
              "element": "string",
              "content": "api"
            }
          ]
        },
        "title": {
          "element": "string",
          "content": ""
        }
      },
      "content": [
        {
          "element": "resource",
          "meta": {
            "title": {
              "element": "string",
              "content": ""
            }
          },
          "attributes": {
            "href": {
              "element": "string",
              "content": "/"
            }
          },
          "content": [
            {
              "element": "transition",
              "meta": {
                "title": {
                  "element": "string",
                  "content": ""
                }
              },
              "content": [
                {
                  "element": "httpTransaction",
                  "content": [
                    {
                      "element": "httpRequest",
                      "attributes": {
                        "method": {
                          "element": "string",
                          "content": "GET"
                        }
                      },
                      "content": []
                    },
                    {
                      "element": "httpResponse",
                      "attributes": {
                        "statusCode": {
                          "element": "string",
                          "content": "204"
                        }
                      },
                      "content": []
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Developing Protagonist

You can use the following steps to build and test Protagonist.

$ git clone --recursive https://github.com/apiaryio/protagonist.git
$ cd protagonist
$ npm install

While iterating on the package, you can use npm run build to compile Protagonist:

$ npm run build
$ npm test

Protagonist is built using node-gyp, you can consult their documentation for further information on the build system.

License

MIT License. See the LICENSE file.