Crafting API – With API-Blueprint, Dredd and Catnap – API-Blueprint
Crafting API – With API-Blueprint, Dredd and Catnap – API-Blueprint
0 0
catnap-talk
On Github mikaa123 / catnap-talk
Crafting API
With API-Blueprint, Dredd and Catnap
@_ms123
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!
What is an API made of?
Resources
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
Catnap
Let's you do just that.
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
Dredd
Takes your API-Blueprint documentation,
and runs your examples against your actual code
╰(*´︶`*)╯
Integrates well with continuous integration systems.
What's next?
Documentation Driven Development?
Write the doc. Let tools help you.
Generate code from your documentation
TDD the resulting code with Dredd