Structuring online documentation for a REST API

Question

I'm building my first Rest API which serialize data to JSON and XML formats. I would like to provide an index page to API clients, where they would be able to choose implemented endpoints.

What information do I need to include to make my API most useful, and how should I organize it?

Answer 1

That's a very complex question for a simple answer.

You may want to take a look at existing API frameworks, like Swagger Specification (OpenAPI), and services like apiary.io and apiblueprint.org.

Also, here's an example of the same REST API described, organized and even styled in three different ways. It may be a good start for you to learn from existing common ways.

• https://api.coinsecure.in/v1
• https://api.coinsecure.in/v1/originalUI
• https://api.coinsecure.in/v1/slateUI#!/Blockchain_Tools/v1_bitcoin_search_txid

At the very top level I think quality REST API docs require at least the following:

• a list of all your API endpoints (base/relative URLs)
• corresponding HTTP GET/POST/... method type for each endpoint
• request/response MIME-type (how to encode params and parse replies)
• a sample request/response, including HTTP headers
• type and format specified for all params, including those in the URL, body and headers
• a brief text description and important notes
• a short code snippet showing the use of the endpoint in popular web programming languages

Also there are a lot of JSON/XML-based doc frameworks which can parse your API definition or schema and generate a convenient set of docs for you. But the choice for a doc generation system depends on your project, language, development environment and many other things.