Building a back-end API layer introduces a whole new layer of coordination between server and client code. While there are many aspects to this delicate dance of communication, one key ingredient to minimizing back-and-forth-confusion-about what-call-does-what, is consistently communicating about your API endpoints.
This is by no means rocket science, but over time I’ve created a template that I now tend to use and have been asked to share. Conveniently when the time comes to publish an API externally, this serves as an invaluable tool for creating public documentation. You can see the markdown template alongside an example in this gist.
Title | The name of your API call Example : Show All Users |
---|---|
URL | The URL structure (path only, no root url) /users or /users/:id or /users?id=:id |
Method | The request type GET | POST | DELETE | PUT |
URL Params | If URL params exist, specify them in accordance with name mentioned in URL section. Separate into optional and required. Required: id=[integer] example: id=12 Optional photo_id=[alphanumeric] example: photo_id=2345kj3 |
Data Params | If making a post request, what should the body payload look like? This is a good time to document your various data constraints too. Example: { u : { email : [string], name : [string], current_password : [alphanumeric] password : [alphanumeric], password_confirmation : [alphanumeric] } }Example: { u : { email : "john@smith.com", name : "John", current_password : "apassw0rd" password : "anewpassw0rd", password_confirmation : "anewpassw0rd" } } |
Success Response | What should the status code be on success and is there any returned data? This is useful when people need to to know what their callbacks should expect! Example: Code: 200 Content: { id : 12 } |
Error Response | Most endpoints will have many ways they can fail. From unauthorized access, to wrongful parameters etc. All of those should be listed here. It might seem repetitive, but it helps prevent assumptions from being made where they shouldn’t be. Example: Code: 401 UNAUTHORIZED Content: { error : "Log in" } OR Code: 422 Unprocessable Entry Content: { error : "Email invalid" } |
Sample Call | Just a sample call to your endpoint in a runnable format ($.ajax call or a curl request) – this makes life easier and more predictable. $.ajax({ url: "/users", dataType: "json", data : { u: { id : 12, email : "john@smith.com" } }, type : "PUT", success : function(r) { console.log(r); } }); |
Notes | This is where all uncertainties, commentary, discussion etc. can go. I recommend timestamping and identifying oneself when leaving comments here. |
Are there other aspects of your API endpoints that you tend to communicate? What additional information should be shared?
Comments
We moved off of Disqus for data privacy and consent concerns, and are currently searching for a new commenting tool.
It’s an interesting choice to use alphanumeric as a data type in these specifications. All alphanumerics are implicitly strings, that have the preconditions of matching [A-Za-z0-9]. Would you use emailaddress as a type? What about other string subtypes that need validation?
Not a criticism, it just seems like a conscious choice to extend your data types like this, and I wonder what the implications are.
Oh I completely agree with you. I think the purpose was more to demonstrate a way to specify it rather than a specific format. I much prefer regex myself =)
Good info here. My question is; are there tools for generating API docs?
dueSouth I’d take a look at http://swagger.wordnik.com/
In the Java world, Enunciate (http://enunciate.codehaus.o… has a great focus on documentation.
If you are in PHP land, Frapi (http://getfrapi.com/) can generate the API itself and the documentation.
a small roundup http://mestachs.wordpress.c…
I’m a developer of MireDot (http://www.miredot.com), which if you’re using Java, might be exactly what you’re looking for. You can take a look at our example documentation and see for yourself: http://www.miredot.com/exam…
This is great. I wish more APIs followed something similar to this.
One thing that is always really, really helpful for API documentation is a clear and precise coverage of rate limits. Their stringency can affect one’s decision to use the API in the first place, so that discussion should happen up-front.
Definitely following this advice for future projects.I came across a pretty neat framework for REST API documentation: http://swagger.wordnik.com/
@dueSouth http://swagger.wordnik.com/ seems to be anice tool for api generation. But haven’t tried it yet. 😉
@ireneros nice post. THX!!!
We’re using JSV (http://tools.ietf.org/html/… for Data Params, and actually generating example JSON directly from the JSV, works great (Our backend is Node.js)
open source that shit !
I’m continually working on convincing management to do that… Might happen, we’ve open sourced a mongodb patch system
https://npmjs.org/package/m…
And the indication so far is that we’ll open source more.
awesome, look forward to seeing the project. what’s the best way to check in on progress?
I guess that would be watching \”e-conomic\” on github.
One thing missing is mime type. An API can easily return different types of data depending on the mime type, so the response examples could change depending on the Accept header.
That is a really good point! I’ve never come across that actually in my own work. Do you have an example of a use case where that happened for you? Would love to hear.
Hi Irene,
A somewhat late response, but how about versioning of your API? Wouldn’t you communicate the specific version when you offer multiple versions?
Regards,
Auke Schotanus
Is there any Automatic documentation tool available
good
Here is a free documentation template for RESTful API’s
https://github.com/SmsNica/…
Wonderful article, it is exactly what i wanted.
Where are headers ?
Thanks good template!
This is very helpful for restful services. but i am looking for soap api documentation template.
Wonderful post..
Great.
Great template. Thank you Irene.
Good post
nice post
useful
Thank you 🙂