API Blueprint can be consumed via an API Blueprint parser which outputs API Elements which can be processed.

• Command line tool
• Parsing service
• Node.js binding
• JavaScript parser
• Native Parser

API Elements

The API Elements is format use recommended format to consume API Blueprint, it supersedes the now deprecated API Blueprint AST.

For example, an HTTP Response can be expressed in API Elements using the following:

{
  "element": "httpResponse",
  "attributes": {
    "statusCode": 200
  },
  "content": [
    {
      "element": "asset",
      "attributes": {
        "contentType": "text/plain"
      },
      "content": "Hello World"
    }
  ]
}

API Elements are built on top of Refract. Refract is a versatile format for recursive structures. Its constructed of many element types which act as building blocks for building data structures and descriptions.

Every Refract element may have 4 attributes, the element name, Refract specific metadata, attributes specified by the element type, and a content value holding the content for the specific element.

NOTE: There are various tools for consuming Refract in JavaScript such as Fury and minim.

Parsing API Blueprint

Using the command line tool

1. Get Drafter command line tool, for macOS using Homebrew:

   $ brew install drafter
   

   See our installation instructions for other platforms

2. Parse API Blueprint into the Refract API Description namespace:

   $ cat << 'EOF' | drafter --format json
   # GET /message
   + Response 200 (text/plain)
   
           Hello World!
   EOF
   {
     "element": "parseResult",
     "content": [
       {
         "element": "category",
   
    ...
   

Using the API Blueprint parsing service

You can use the API Blueprint parsing service, full API documentation for the service can be found on Apiary.

$ curl -X POST
    --header "Content-Type: text/vnd.apiblueprint" \
    --header "Accept: application/vnd.refract.parse-result+json" \
    --data-binary "# My API Blueprint" \
    https://api.apiblueprint.org/parser
{"element":"parseResult","content":[{"element":"category","meta":{"classes":["api"],"title":"My API Blueprint"},"content":[]}]}

Using a parser binding (Node.js)

1. Install binding for your language (e.g. Drafter NPM for Node.js)

   $ npm install drafter
   

2. Parse your API Blueprint into Refract

   var drafter = require('drafter');
   
   var blueprint = '''
   # GET /message
   + Response 200 (text/plain)
   
           Hello World!
   ''';
   
   protagonist.parse(blueprint, function(error, result) {
       ...
   });
   

Using drafter.js (Pure JavaScript parser)

drafter.js is a pure JavaScript version of the drafter library designed to work in web browsers. It exposes a single parse function which takes an API Blueprint string and options and returns the Refract Parse Result.

1. Install drafter.js

   You may also download drafter.js from the releases page and reference it in HTML.

   <script src="./drafter.js"></script>
   <script src="./drafter.js.mem"></script>
   

2. Parse your API Blueprint into Refract

   var blueprint = '''
   # GET /message
   + Response 200 (text/plain)
   
           Hello World!
   ''';
   
   try {
     var res = drafter.parse(blueprint, {exportSourcemap: true});
     console.log(res);
   } catch (err) {
     console.log(err);
   }
   

Using the native parser interface (C/C++)

1. Install Drafter

2. Parse your API Blueprint

   #include <drafter/drafter.h>
   
   const char *blueprint =
     "# My API\n"
     "## GET /message\n"
     "+ Response 200 (text/plain)\n"
     "\n"
     "      Hello World!\n";
   
   drafter_parse_options* pOpts = drafter_init_parse_options();
   drafter_set_name_required(pOpts);
   
   drafter_serialize_options* sOpts = drafter_init_serialize_options();
   drafter_set_format(sOpts, DRAFTER_SERIALIZE_JSON);
   
   char *result = NULL;
   if (DRAFTER_OK == drafter_parse_blueprint_to(blueprint, &result, pOpts, sOpts)) {
       printf("%s\n", result);
       free(result);
   }
   

   Please see Drafter for full API documentation.