Is there a best practices to document an API for public?

Published 8 months ago by malhayek

I have an API that is written on a top of Laravel 5.5. I need to write some sort of documentation for it so people know how to use it.

Is there is a best practice document that I can use as a guide to help me writing the document?

Is there an API example of a Laravel project with document that I can look at? Or is there a standard documentation template that the community use with Laravel based APIs?

jbloomstrom

This could be a good starting point: https://swagger.io/docs/specification/about/

burlresearch

Swagger is great, no doubt. However, it is sometimes a little too opinionated, or over-the-top.

To add to your options, when I've wanted code documentation that was a little less demanding (read: simpler for project needs), I have used these, for your consideration:

  1. APIDOC: http://apidocjs.com/
  2. APIGEN: http://www.apigen.org/

Both of which serve slightly different purposes, but are quite effective.

malhayek

@jbloomstrom @burlresearch Thank you for the input and help with this.

I created a small dummy api documentation page which can be found here https://jsfiddle.net/DTcHh/41786/

Can you please share with me your thought on this style? Is it missing anything or is it complete? Does it do a good job explaining everything?

Thank you

burlresearch

That looks quite nice - however it's very "programmer-y". If I were a programmer taking over this project much of this information could be inferred from artisan route:list, except prettier in this format.

Perhaps some information I'd find useful would be:

  1. Plain language description of what 'assets' are, maybe how many of them there are, and why they are useful to the company
  2. Examples! example call strings (using curl or httpie), and actual response bodies
  3. You should mention the format - I'd assume JSON, but it's worth specifying
  4. there are 401 error codes - so how can I authenticate as a user?

Stuff like that?

malhayek

@burlresearch thank you for your feedback again. artisan route:list will give you most of that info if your the developer but an outside person who is looking to integrate their system won't have access to that.

Regarding our 4 bullet, In a typical Laravel based API, how would one establish connection? I mean how would one trying to interact with the API generate a token? Does the token change ofter like the csrf token or is it like a session id?

Thank you

burlresearch

For sure - this documentation will be useful to outside programmers. So this will be good documentation. But I would be an "outside programmer" if I used this API - so I'd want to know:

  1. if I receive a 401-Unauthorized: then how can I become authorized?
  2. if my call is successful, what format (JSON?) and what fields (examples?) will I receive?

These are just ideas - you know who your clients will be. Try to put yourself in their shoes (not knowing anything about your API), and imagine what questions you could answer to make their job, of using your API, as easy as possible.

Please sign in or create an account to participate in this conversation.