Create a gist now

Instantly share code, notes, and snippets.

What would you like to do?
Documenting your REST API

Title

<Additional information about your API call. Try to use verbs that match both request type (fetching vs modifying) and plurality (one vs multiple).>

  • URL

    <The URL Structure (path only, no root url)>

  • 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. Document data constraints.>

    Required:

    id=[integer]

    Optional:

    photo_id=[alphanumeric]

  • Data Params

    <If making a post request, what should the body payload look like? URL Params rules apply here too.>

  • 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!>

    • 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 liste d here. It might seem repetitive, but it helps prevent assumptions from being made where they should be.>

    • 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.>

  • Notes:

    <This is where all uncertainties, commentary, discussion etc. can go. I recommend timestamping and identifying oneself when leaving comments here.>

Show User

Returns json data about a single user.

  • URL

    /users/:id

  • Method:

    GET

  • URL Params

    Required:

    id=[integer]

  • Data Params

    None

  • Success Response:

    • Code: 200
      Content: { id : 12, name : "Michael Bloom" }
  • Error Response:

    • Code: 404 NOT FOUND
      Content: { error : "User doesn't exist" }

    OR

    • Code: 401 UNAUTHORIZED
      Content: { error : "You are unauthorized to make this request." }
  • Sample Call:

      $.ajax({
        url: "/users/1",
        dataType: "json",
        type : "GET",
        success : function(r) {
          console.log(r);
        }
      });

Nice Example - Thanks for sharing

It is nice. Thanks.

Thank you!

nisxiya commented May 25, 2015

looks really nice. It gives me an insight on how to write a nice API for public.

leyafo commented Jun 29, 2015

Thanks.

Thanks a lot

Thank you! very good template!

Thanks!

zoldello commented Nov 5, 2015

Awesome++

Nice!

Thanks Iros for sharing. Nice example with formatting.

Thanks for sharing. Simple Template. I'm left with one question though.
How would you describe the Header part; to differentiate from Data Param? For instance, the Content-Type and Authorization.

Nice formatting dude

Awesome!

it's really nice, thanks for sharing

too long imo, imagine you have 10 endpoints with wildcards in them, would blow out of the proportion and make this unreadable

awesome πŸ‘

thanx !

fabulous!

Awsome 5 Stars for a Basic API Doc Template

Super!

Nice!

thanks for such a nice template

Awesome πŸ‘

uginm102 commented Jun 3, 2016

Great

gbazilio commented Jun 5, 2016

Nice!

thanks for sharing!

Nice template! Thanks!

neeraj9 commented Jul 30, 2016

Just what I was looking for. Thanks for sharing.

whlsxl commented Aug 3, 2016

Thanks!!!!

Thank you

idtyu commented Aug 8, 2016

Thank you!

Thanks for the sharing.

hanhdt commented Aug 12, 2016

Thank you for sharing examples!

Thanks

Using it! πŸ‘

Using this for my API doc

fabulous!

Thanks, nice template!
The only problem is that it doesn't really fit the case when there are several operations available for the same URL (like POST/GET/PUT ...)
In this case, all of them could have the same header as well as URL but different reminder :)

nmh0391 commented Oct 10, 2016

Simple yet elegant. Thanks!

Thanks for sharing.

moiroca commented Oct 26, 2016

Thanks!

suvajit commented Oct 29, 2016

Exactly what I was looking for. Good one. Thanks

You can include the header section.

DAC001 commented Nov 12, 2016

Thanks buddy! πŸ‘

Otienoh commented Nov 16, 2016

So useful, Thanks so MUCH

edsu commented Nov 18, 2016

Thanks for this, it's very clean! Would you put query parameters in the URL parameters area?

Thanks for this, it's was very helpfull

NickNaso commented Dec 8, 2016

Thanks good example!

So good!

good

aresowj commented Jan 23, 2017

Very nice examples, thanks!

For anyone wanting to read a bit more, see https://bocoup.com/weblog/documenting-your-api for a blog post that @iros wrote about this.

Thanks.

Thanks πŸ‘

PERFECT!

aindong commented Apr 18, 2017

Thank you so much!

Really cool! I created a small plugin for node, to generate documentation from code comments in such way. https://www.npmjs.com/package/simple-rest-docs

amixpal commented May 4, 2017

Awesome !

thanks much. Very helpful

Thanks

Thanks

hanx11 commented Jun 15, 2017

Thanks, but can you give an example of rst?

Good example. Helpful...

Qolzam commented Jul 22, 2017

Thank you so much. +1:

If I'd like to add header to request. then how can I do ?
ie. x-access-token: ''

Thanks for this great reference.

nice example. very helpful πŸ‘

Thank You !

nice !

saledwin commented Sep 13, 2017

Nice example. Thanks!

Nice example. πŸ‘

Thank you a lot!

yuda110 commented Oct 31, 2017

Thanks!

Nice example, thanks

nice example , thanks for sharing

so nice

tantq commented Jan 19, 2018

Thank you so much

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment