Skip to content

Instantly share code, notes, and snippets.

Embed
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);
        }
      });
@donlovett

This comment has been minimized.

Copy link

commented Nov 25, 2014

Nice Example - Thanks for sharing

@sheffler

This comment has been minimized.

Copy link

commented Jan 26, 2015

It is nice. Thanks.

@ahuntcirruspath

This comment has been minimized.

Copy link

commented Feb 13, 2015

Thank you!

@nisxiya

This comment has been minimized.

Copy link

commented May 25, 2015

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

@leyafo

This comment has been minimized.

Copy link

commented Jun 29, 2015

Thanks.

@allergictoeng

This comment has been minimized.

Copy link

commented Sep 16, 2015

Thanks a lot

@yoonkwon

This comment has been minimized.

Copy link

commented Sep 25, 2015

Thank you! very good template!

@devHudi

This comment has been minimized.

Copy link

commented Oct 15, 2015

Thanks!

@zoldello

This comment has been minimized.

Copy link

commented Nov 5, 2015

Awesome++

@rafagomes

This comment has been minimized.

Copy link

commented Nov 21, 2015

Nice!

@shridhaarchippaa

This comment has been minimized.

Copy link

commented Nov 24, 2015

Thanks Iros for sharing. Nice example with formatting.

@vaananart

This comment has been minimized.

Copy link

commented Nov 26, 2015

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.

@ardha2008

This comment has been minimized.

Copy link

commented Dec 11, 2015

Nice formatting dude

@IuryAlves

This comment has been minimized.

Copy link

commented Jan 11, 2016

Awesome!

@wnulilalbab

This comment has been minimized.

Copy link

commented Feb 5, 2016

it's really nice, thanks for sharing

@stanislavromanov

This comment has been minimized.

Copy link

commented Feb 23, 2016

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

@webhacking

This comment has been minimized.

Copy link

commented Mar 20, 2016

awesome ๐Ÿ‘

@zazapeta

This comment has been minimized.

Copy link

commented Apr 14, 2016

thanx !

@yevgnenll

This comment has been minimized.

Copy link

commented Apr 22, 2016

fabulous!

@pradeeppdt

This comment has been minimized.

Copy link

commented Apr 22, 2016

Awsome 5 Stars for a Basic API Doc Template

@twig2let

This comment has been minimized.

Copy link

commented Apr 28, 2016

Super!

@Nicholk24

This comment has been minimized.

Copy link

commented May 17, 2016

Nice!

@Bharat9623925980

This comment has been minimized.

Copy link

commented May 21, 2016

thanks for such a nice template

@saginadir

This comment has been minimized.

Copy link

commented May 25, 2016

Awesome ๐Ÿ‘

@uginm102

This comment has been minimized.

Copy link

commented Jun 3, 2016

Great

@gbazilio

This comment has been minimized.

Copy link

commented Jun 5, 2016

Nice!

@toymak3r

This comment has been minimized.

Copy link

commented Jun 17, 2016

thanks for sharing!

@luisdaher

This comment has been minimized.

Copy link

commented Jun 29, 2016

Nice template! Thanks!

@neeraj9

This comment has been minimized.

Copy link

commented Jul 30, 2016

Just what I was looking for. Thanks for sharing.

@whlsxl

This comment has been minimized.

Copy link

commented Aug 3, 2016

Thanks!!!!

@nitish1402

This comment has been minimized.

Copy link

commented Aug 4, 2016

Thank you

@idtyu

This comment has been minimized.

Copy link

commented Aug 8, 2016

Thank you!

@lalitsingh198910

This comment has been minimized.

Copy link

commented Aug 9, 2016

Thanks for the sharing.

@hanhdt

This comment has been minimized.

Copy link

commented Aug 12, 2016

Thank you for sharing examples!

@ttruongatl

This comment has been minimized.

Copy link

commented Aug 13, 2016

Thanks

@marcellodesales

This comment has been minimized.

Copy link

commented Aug 17, 2016

Using it! ๐Ÿ‘

@k-schmidt

This comment has been minimized.

Copy link

commented Aug 17, 2016

Using this for my API doc

@spabloramirez

This comment has been minimized.

Copy link

commented Aug 26, 2016

fabulous!

@longtimeago

This comment has been minimized.

Copy link

commented Sep 21, 2016

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

This comment has been minimized.

Copy link

commented Oct 10, 2016

Simple yet elegant. Thanks!

@fsalehpour

This comment has been minimized.

Copy link

commented Oct 15, 2016

Thanks for sharing.

@moiroca

This comment has been minimized.

Copy link

commented Oct 26, 2016

Thanks!

@suvajit

This comment has been minimized.

Copy link

commented Oct 29, 2016

Exactly what I was looking for. Good one. Thanks

@jethrolai

This comment has been minimized.

Copy link

commented Nov 7, 2016

You can include the header section.

@DAC001

This comment has been minimized.

Copy link

commented Nov 12, 2016

Thanks buddy! ๐Ÿ‘

@Otienoh

This comment has been minimized.

Copy link

commented Nov 16, 2016

So useful, Thanks so MUCH

@edsu

This comment has been minimized.

Copy link

commented Nov 18, 2016

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

@egomez-eendlabs

This comment has been minimized.

Copy link

commented Nov 22, 2016

Thanks for this, it's was very helpfull

@NickNaso

This comment has been minimized.

Copy link

commented Dec 8, 2016

Thanks good example!

@shiqingjie

This comment has been minimized.

Copy link

commented Dec 22, 2016

So good!

@anovanmaximuz

This comment has been minimized.

Copy link

commented Jan 1, 2017

good

@aresowj

This comment has been minimized.

Copy link

commented Jan 23, 2017

Very nice examples, thanks!

@jordanmkoncz

This comment has been minimized.

Copy link

commented Jan 27, 2017

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.

@xmanemran

This comment has been minimized.

Copy link

commented Feb 5, 2017

Thanks.

@Snehasispanigrahi

This comment has been minimized.

Copy link

commented Mar 27, 2017

Thanks ๐Ÿ‘

@binzailani3136

This comment has been minimized.

Copy link

commented Mar 28, 2017

PERFECT!

@aindong

This comment has been minimized.

Copy link

commented Apr 18, 2017

Thank you so much!

@maciejmatu

This comment has been minimized.

Copy link

commented Apr 20, 2017

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

@sstrycker-zspace

This comment has been minimized.

Copy link

commented Apr 28, 2017

Great!

@amixpal

This comment has been minimized.

Copy link

commented May 4, 2017

Awesome !

@code-gems

This comment has been minimized.

Copy link

commented May 9, 2017

thanks much. Very helpful

@cyrildewit

This comment has been minimized.

Copy link

commented May 17, 2017

Thanks

@emaalouf

This comment has been minimized.

Copy link

commented Jun 13, 2017

Thanks

@hanx11

This comment has been minimized.

Copy link

commented Jun 15, 2017

Thanks, but can you give an example of rst?

@rajanjain

This comment has been minimized.

Copy link

commented Jun 28, 2017

Good example. Helpful...

@Qolzam

This comment has been minimized.

Copy link

commented Jul 22, 2017

Thank you so much. +1:

@toantd90

This comment has been minimized.

Copy link

commented Jul 26, 2017

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

@naveeniq

This comment has been minimized.

Copy link

commented Jul 26, 2017

Thanks for this great reference.

@prembhaskal

This comment has been minimized.

Copy link

commented Jul 30, 2017

nice example. very helpful ๐Ÿ‘

@AshishBagdane

This comment has been minimized.

Copy link

commented Aug 6, 2017

Thank You !

@FlomeWorld

This comment has been minimized.

Copy link

commented Sep 8, 2017

nice !

@saledwin

This comment has been minimized.

Copy link

commented Sep 13, 2017

Nice example. Thanks!

@wongzigii

This comment has been minimized.

Copy link

commented Sep 18, 2017

Nice example. ๐Ÿ‘

@ecleipteon

This comment has been minimized.

Copy link

commented Sep 24, 2017

Thank you a lot!

@yuda110

This comment has been minimized.

Copy link

commented Oct 31, 2017

Thanks!

@MeTaLiKiD

This comment has been minimized.

Copy link

commented Nov 16, 2017

Nice example, thanks

@keshav1990

This comment has been minimized.

Copy link

commented Nov 24, 2017

nice example , thanks for sharing

@pourya2374

This comment has been minimized.

Copy link

commented Jan 16, 2018

so nice

@tantq

This comment has been minimized.

Copy link

commented Jan 19, 2018

Thank you so much

@mtm9999

This comment has been minimized.

Copy link

commented Feb 19, 2018

Thanks!

@codeblooded

This comment has been minimized.

Copy link

commented Feb 21, 2018

This is so beautiful, I had to tweet and post on Facebook. Wow... Iโ€™m a geek.

@dotperinch

This comment has been minimized.

Copy link

commented Feb 28, 2018

Wow! Thank you for sharing this! ๐Ÿ‘

@psy21d

This comment has been minimized.

Copy link

commented Mar 24, 2018

Okay, I really need this.

@MichaelCurrie

This comment has been minimized.

Copy link

commented Mar 31, 2018

It's much more attractive to render this as an actual table, which actually matches the format you used in your blog (https://bocoup.com/blog/documenting-your-api)

Example API Entry

Title Get Scenario
URL /scenario
Method GET
URL Parameters Required:
id=[integer]
Success Response Code: 200
Content:{"id": 12}
Error Response Code: 401 UNAUTHORIZED
Content:{"error": "Log in"}
Error Response Code: 422 UNPROCESSABLE ENTRY
Content:{"error": "Email Invalid"}
Sample Request /scenario?id=55
Notes
$.ajax({
  url: "/scenario?id=55",
  dataType: "json",
  type: "GET",
  success: function(r) {
    console.log(r);
}});
@aleruete

This comment has been minimized.

Copy link

commented May 8, 2018

Thank You!

@airangel0120

This comment has been minimized.

Copy link

commented May 14, 2018

thank you!

@ztchia

This comment has been minimized.

Copy link

commented Jun 8, 2018

Thank you for the template. It's absolutely incredible!

@dhaneshwarsingh

This comment has been minimized.

Copy link

commented Jul 24, 2018

Thank you for sharing nice document with example. Great work!.

@chaimkut

This comment has been minimized.

Copy link

commented Aug 5, 2018

Note: Usage of : in section headers in the template is inconsistent
Example, URL doesn't have :, Method: does have :. Might be worthwhile to standardize.

@599316527

This comment has been minimized.

Copy link

commented Nov 9, 2018

How to specify request/response headers

@v4lerio

This comment has been minimized.

Copy link

commented Jan 10, 2019

Thanks for sharing

@alberss

This comment has been minimized.

Copy link

commented Feb 25, 2019

๐Ÿฅ‡ ๐Ÿ™ Thanks!

@bitfishxyz

This comment has been minimized.

Copy link

commented Mar 12, 2019

Sometimes, you can write you error response in an indepentant place

@clombardi

This comment has been minimized.

Copy link

commented Apr 8, 2019

Thanks a lot, I am using this template to document an API to be released soon.

@Jaymo

This comment has been minimized.

Copy link

commented Apr 25, 2019

Thanks for sharing this, using it to document APIs I use

@camilamiz

This comment has been minimized.

Copy link

commented May 8, 2019

Thank you so much! Very useful!

@raulinoneto

This comment has been minimized.

Copy link

commented May 10, 2019

Thank you!! I'll use it

@phungrk

This comment has been minimized.

Copy link

commented May 24, 2019

Thank you!!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You canโ€™t perform that action at this time.