SOA Series Part 3: Documenting and Generating your APIs

This is the third in a series of seven posts on service-oriented architecture derived from a workshop conducted by Cloves Carneiro and Tim Schmelmer at Abril Pro Ruby. The series is called SOA from Day One – A love story in 7 parts.

APIs will only be used when there is documentation on how to use them. In part three of this series of articles we recommend you think about how to structure and document your APIs from day one.

Standards and Consistency

To freely quote Andrew S. Tannenbaum:

“The Good Thing About Standards: there are so many of them”

Even if you say your API is RESTful, it doesn’t really say much in detail. Spend the time to negotiate guidelines internal to your organization. Spend some time thinking about all the various options and degrees of freedom, and then, most importantly, stick to what you picked. The principal of least surprise will pay off for your clients, and for yourself.

  • What HTTP Status (success and error) codes will you use for which situations
    • 204 or 200 response codes for successful POSTs/PUTs?
    • consistency around the 4xx code range
  • Will there be additional error messaging in the body?
  • Where does authentication go?
    • into the header, in a URL parameter, …
  • What approach will we take to our resource hierarchy
    • Truly “RESTful”, or are there some “RPC” like endpoints (/inventory_items/near_city)
  • Will we support true ‘hypermedia’ references with self-discover, or will we simply show resource IDs?
    • {'id': 123'} vs. {'uri': ''}
  • What about versioning information? Where will it go?

Heroku recently open-sourced its own HTTP API Design Guidelines to answer some of these questions for their use cases, and they are inviting everyone in the community to contribute.

Specifying your Endpoints

“What do you mean, I need to specify my application’s endpoints … can’t you read the routes file?!”

No, that is unfortunately just not good enough, sorry! You just spent all this time going over some standards and consistency, now spend a little more time to define your API in a “machine digestible”, declarative format.

This specification should preferably be published at a (well-known) endpoint in your application, so that your clients can auto-discover your APIs … and maybe even auto-generate client code.

Using an Interface Definition Languages (IDLs)

We have found during our careers that IDLs are a very convenient thing, and that the benefits by far outweigh the effort. And no: you don’t need to learn JEE, WS-* or XML to use an IDL.

JSON-RPC, ProtoBuf, Thrift, JSON-Schema with Heroku’s prmd (all of which have Ruby bindings), and the like, all follow the same principle:

  • you specify your API in some schema
  • client libraries / gems, and often even service-side stubs are generated for you; either via a separate ‘build step’ (rake tasks, e.g.) ahead of time, or even ‘on the fly’ when clients are consuming the IDL specification of your published endpoints.

Best of all, most of these tools work cross-language (Java shop, anyone?), and often have support for auto-generating human-readable docs.

What we use: Swagger

Specification via JSON Schema

Swaggerâ„¢ is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services.”

In essence, you use JSON to specify your endpoints, according to a well-defined JSON schema. A suite of surrounding tools help with auto-generating the JSON based on annotations or DSLs, auto-generating client and service stub code (across a growing set of languages). The project is open-source, maintained by Wordnik.

See here and here for the inventory-service’s JSON specs.

Ruby Tools

Here are some of the Ruby-specific projects surrounding swagger.

swagger-docs / swagger-yard

These two (competing?) gems allow you to specify your APIs in a Ruby DSL, and then generating the JSON specification via a separate rake task. See some sample swagger-docs DSL code that describes the inventory-service.

Unfortunately, neither of these two gems is entirely mature, but hey: it’s Open-Source, so go and contribute!

swagger-codegen / grape-swagger

Swagger-codegen is the general project to generate client code by parsing your Swagger JSON specs. Ruby support exists, albeit less ‘stable’ than for scala. Swagger-grape is a gem to add swagger compliant documentation to a grape API.

Killer feature: Service Explorer

A swagger subproject called swagger-ui is essentially a single HTML page, plus some spiffy CSS and JavaScript to consume your JSON API specs. In return, it generates a very useful ‘service explorer’ UI. This UI lists all your endpoints, and gives you the option to fire single requests for each of them to your server.

Pasted Graphic.png

You can see it in action in each of the root pages for our sample services:

Exercise “Generating Documentation for your APIs”

If you followed along with part 2, and want to play around with documenting one of your services with swagger, we suggest you try tackling the following exercises based on the sample code:

  • make these links work with your own heroku apps
    • Tip: you will need to adapt the URIs in your swagger UI index.html page, as well as some URIs inside the API JSON specs.

Previous articles in this series