You are here

How to Design Static REST API Documentation

You need good API docs if developers are going to have success with their integrations. Just as importantly, your docs are also like marketing material. If on first reading, the prospective user doesn’t understand how your product works or thinks it would be a nightmare to integrate, you’re in trouble. Derric Gilling, CEO/co-founder at Moesif, having put a lot of thought into the Moesif docs, gives you the lowdown on how to design good REST API docs

First choice off the bat is how to organize your docs at the highest level. There are three schools of thought: centralized docs with a separate API reference, centralized docs and no separate reference or decentralized docs. Your preference will depend on your needs. 

Moesif along with Stripe, among others go for option one. The main motivation is to serve two types of reader: developers looking at overall integration or those looking for the particulars of the API. In cases where you expect most users to integrate your API through a wrapper or SDK, it makes sense to put the REST API docs someplace else. The overall benefits of the approach are: making sure the right users go to the right place and the ability to have different layouts. The downsides are: it can put your API reference in the shade and it doesn’t really work if you only have one level of integration (i.e. no SDKs, wrapper libraries). 

Companies like Mixpanel and Square on the other hand centralize docs but have no separate API reference. This choice makes sense when your docs are targeting non-developers such as product managers. The risk with a separate API reference is that you put off these users if they land in the wrong place. The benefit of this approach is that you make sure the REST API reference is no second-class citizen. The downsides are you have to compromise on layout and the docs can get confusing if you have a lot of documentation.

The decentralized docs approach is favored by the likes of Twilio. Twilio siloes its docs according to product (e.g. SMS, video, authentication). This makes sense where readers are only interested in one part of the API for one product and don’t want to be distracted by talk of other products. The big plus of this approach is that you can just read the part of the docs that is relevant to you. You can also scale the docs by product team. The downsides on the other hand are that you can create artificial silos between products and it can be hard to organise get started guides when relevant information is split across products. 

Derric concludes his post by listing some useful tips on how to design and publish your docs. Without question, go for sticky navigation so the user doesn’t need to scroll to the top to go where he wants. Preferably have sidebar navigation with an accordion design to avoid clutter. In a similar vein, Derric recommends saving the user’s scroll state so he can go back to the same place after refreshing the page.  

Be sure to read the next API Design article: Why Improbable Ditched REST for gRPC

Original Article

Designing Good Static REST API Documentation