Developers

Developing tools for API Blueprint

NOTE: This article is outdated, proceed with care.

It is best to consume the API Blueprint AST directly either via a binding interface or the native parser interface.

Alternatively, you can use the parser command line tool and then process its output AST media type.

Using a parser binding (Node.js)

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

   $ npm install protagonist

2. Parse your API Blueprint into its AST

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

Using the command line tool

1. Get Drafter command line tool

   $ brew install --HEAD \
       https://raw.github.com/apiaryio/drafter/master/tools/homebrew/drafter.rb

   Build notes for Linux and Windows.

2. Parse API Blueprint into its AST media type

   $ cat << 'EOF' | drafter --type ast --format json
   # GET /message
   + Response 200 (text/plain)
   
           Hello World!
   EOF
   {
     "_version": "1.0",
     "metadata": {},
     "name": "",
     "description": "",
    
    ...

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

1. Build Drafter

   $ ./configure
   $ make

   See full build instructions

2. Parse your API Blueprint into its AST

   #include "drafter.h"         // Blueprint Parser
   #include "SerializeResult.h" // Result Wrapper for serialization
   #include "sosJSON.h"         // Serializer
   
    mdp::ByteBuffer blueprint = R"(
   # My API
   ## GET /message
    + Response 200 (text/plain)
   
           Hello World!
   )";
   
   // Blueprint parsing
    snowcrash::ParseResult<snowcrash::Blueprint> ast;
    drafter::ParseBlueprint(blueprint, 0, ast);
   
    std::cout << "API Name: " << ast.node.name << std::endl;
   
   // Serialization to JSON format
    sos::SerializeJSON serializer;
    serializer.process(drafter::WrapResult(ast.node, drafter::WrapperOptions(drafter::RefractASTType)), std::cout);

Using the API Blueprint parsing service

$ 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":[]}]}

Full API documentation for the API Blueprint parsing service can be found at Apiary.