Crafting API

API-Blueprint

Lets you document APIs in a human-readable way.

The resulting documentation is processable by machines.

It lets you define transactions

By giving examples

An API-Blueprint parser creates an AST.

This AST is used to create wonderous tooling!

Resource

some service that lives at a URI and that has one or more representations.

actions

HTTP transactions

• GET
• POST
• PUT
• PATCH
• DELETE

Representation

The actual state of the resource, represented according to a

media type

• text/plain
• application/xml
• application/json+hal

Resource

var userResource = makeResource('user', '/users/:userId')
          

Define representations

  .representation(function (user) {
    return pick(user, 'username', 'email');
  })

  .representation('partial', function (user) {
    return pick(user, 'username');
  })

Define actions

  .get(function (req, res) {
    User.findOne({ _id: req.params.userId }, function (err, user) {
        user && res.send(200, userResource(user));
    });
  });

Why

Makes API-Blueprint concepts first-class citizen in our code

• Shared vocabulary
• Lets us write API the way we think about them
• Framework agnostic
• Just a library

On abstractions

“Pick the right ones, and programming will flow naturally from design; modules will have small and simple interfaces; and new functionality will more likely fit in without extensive reorganization. Pick the wrong ones, and programming will be a series of nasty surprises: interfaces will become baroque and clumsy as they are forced to accommodate unanticipated interactions, and even the simplest of changes will be hard to make.”

—Daniel Jackson, MIT Professor

Takes your API-Blueprint documentation,

and runs your examples against your actual code

╰(*´︶`*)╯

Integrates well with continuous integration systems.

Documentation Driven Development?

Write the doc. Let tools help you.

Generate code from your documentation

TDD the resulting code with Dredd

Create a better
“developer experience”.