RESTful API Unconference Session


Category: Unconference Session

18 May 2015, unconf session on RESTful APIs.

FYI, i’ve shared my notes – and others in the session will do the same:

Some user introls

Oldschool API ref
Autodesk — global API
Mike – Forgerock, showed docs
Steven API tech writer, square
Build as they go
Seems to require humans to write compelling API examples

Ruby, Python, curl, C+, objective C, etc.
Some arbitrarily say “we just use curl, anything else, YMMV”

Python examples — most “pseudo-codish programming language”

Square example:
Script that checks every endpoint every hour

explicit — how you auth — different for everyone — token in URI / header

MPM docs

Discussion on versioning
— not just a modified version of the same doc, especially when endpoints change

Square works with a simplifedish version of DITA for API docs

1 page per service?


These are my notes from the unconference session:

Example API calls - what’s the best language/format?

  • curl is popular, but not always the clearest
  • some ppl thought Python was more explicit/universal

Useful to provide a list of good REST libs your client can use for various languages

Discussion of limiting level of destruction in API playground - client data, or sandbox?

Discussion of handling versioning. Autogen can help here w/ annotations.

Discussion of handling deprecation, especially w/ SEO. One solution: put “deprecated” right in the title, this gets indexed by search engines.

Doc source format? Lots of variation: xml, docbook, MD, RST/sphinx.

  • LaTeX to PDF can look surprisingly nice

One page per endpoint? Consensus was no, do what Stripe does, or at least one page per service if you have a really big API. This supports CTRL-F search, this is what devs want to do/are doing. New Relic has some js in their help that detects ctrl-F and expands all collapsed text to support search (very clever monkeys).


Speaking of Stripe-style docs, Slate made for a really lovely Stripe-esque set of API docs for a project I was working on recently.

I’m a big ReST + Sphinx fan for most stuff, but for API docs, I thought Slate really met our needs. The devs who were working on the API also liked that they could provide the code examples themselves, without much wading into the nitty gritty of how the docs build worked, and since I was setting it up for a friend, I liked that I didn’t have to hold their hands much. It does live preview as well. Would totally use again.


Slate is manual, right? That is to say, the content is entirely external to the code, there aren’t any generated bits? Apologies for not looking it up, but the whole generated/manual thing is sort of relevant here, too. (Not advocating for one or the other, either – my take is the content matters, where you put said content is secondary.)


Correct! It’s manual – one could probably write some magic to ingest it in, but it’s not out of the box.


Dang, I’m bummed I missed this!

At GitHub we use Markdown for the content and nanoc to generate the site:

But we’re looking very closely at using JSONSchema as a means of validating our code, and as generating documentation:

I’d be very curious to know about Square’s “hourly endpoint check” script, as well as the “simplifedish version of DITA for API docs.” Anyone know who to ping over there for more info?