Menu
I'm writing a specification for a RESTful API for a new internal web service. It's not hugely long and fairly simple, but even so, it's my first time using strict REST (as opposed to cheating for practical reasons - avoiding PUT and DELETE because they're a pain in PHP, and so on). I was wondering if there were any standard methods or best practices for documenting a REST interface? I want the rest of the team to understand it at a glance, and for anyone that wants to write a client to be able to do so without understanding the underlying code.
859
Write in a writing tool Write as much as possible in a format that's designed for writing. “Writing documentation in annotations is horrendous,” Andy explained. Consider a tool such as ASCIIDoctor, a plain-text writing format for authoring documentation, notes, books, and also a publication toolchain.
Data Formats Most API requests will return content from the server that the client needs to interpret. Rarely is this content plain text—usually, it will use a structured data format. While REST does not specify any data formats, JSON and XML are the two most commonly used.
Sure, REST APIs should ideally use HATEOAS and be hypertext driven (with heavy use of media types), but also having simple human-friendly documentation for developers to work off of is helpful.
Some specific tools that are helpful for generating documentation like this:
165
I've been using http://apiary.io, which is pretty nice. You can also export the API documentation to github.
44
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
