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

@donlovett donlovett commented Nov 25, 2014

Nice Example - Thanks for sharing

@sheffler

This comment has been minimized.

Copy link

@sheffler sheffler commented Jan 26, 2015

It is nice. Thanks.

@ahuntcirruspath

This comment has been minimized.

Copy link

@ahuntcirruspath ahuntcirruspath commented Feb 13, 2015

Thank you!

@nisxiya

This comment has been minimized.

Copy link

@nisxiya nisxiya 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

@leyafo leyafo commented Jun 29, 2015

Thanks.

@allergictoeng

This comment has been minimized.

Copy link

@allergictoeng allergictoeng commented Sep 16, 2015

Thanks a lot

@yoonkwon

This comment has been minimized.

Copy link

@yoonkwon yoonkwon commented Sep 25, 2015

Thank you! very good template!

@devHudi

This comment has been minimized.

Copy link

@devHudi devHudi commented Oct 15, 2015

Thanks!

@zoldello

This comment has been minimized.

Copy link

@zoldello zoldello commented Nov 5, 2015

Awesome++

@rafagomes

This comment has been minimized.

Copy link

@rafagomes rafagomes commented Nov 21, 2015

Nice!

@shridhaarchippaa

This comment has been minimized.

Copy link

@shridhaarchippaa shridhaarchippaa commented Nov 24, 2015

Thanks Iros for sharing. Nice example with formatting.

@vaananart

This comment has been minimized.

Copy link

@vaananart vaananart 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

@ardha2008 ardha2008 commented Dec 11, 2015

Nice formatting dude

@IuryAlves

This comment has been minimized.

Copy link

@IuryAlves IuryAlves commented Jan 11, 2016

Awesome!

@wnulilalbab

This comment has been minimized.

Copy link

@wnulilalbab wnulilalbab commented Feb 5, 2016

it's really nice, thanks for sharing

@stanislavromanov

This comment has been minimized.

Copy link

@stanislavromanov stanislavromanov 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

@webhacking webhacking commented Mar 20, 2016

awesome ๐Ÿ‘

@zazapeta

This comment has been minimized.

Copy link

@zazapeta zazapeta commented Apr 14, 2016

thanx !

@yevgnenll

This comment has been minimized.

Copy link

@yevgnenll yevgnenll commented Apr 22, 2016

fabulous!

@pradeeppdt

This comment has been minimized.

Copy link

@pradeeppdt pradeeppdt commented Apr 22, 2016

Awsome 5 Stars for a Basic API Doc Template

@twig2let

This comment has been minimized.

Copy link

@twig2let twig2let commented Apr 28, 2016

Super!

@Nicholk24

This comment has been minimized.

Copy link

@Nicholk24 Nicholk24 commented May 17, 2016

Nice!

@Bharat9623925980

This comment has been minimized.

Copy link

@Bharat9623925980 Bharat9623925980 commented May 21, 2016

thanks for such a nice template

@saginadir

This comment has been minimized.

Copy link

@saginadir saginadir commented May 25, 2016

Awesome ๐Ÿ‘

@uginm102

This comment has been minimized.

Copy link

@uginm102 uginm102 commented Jun 3, 2016

Great

@gbazilio

This comment has been minimized.

Copy link

@gbazilio gbazilio commented Jun 5, 2016

Nice!

@toymak3r

This comment has been minimized.

Copy link

@toymak3r toymak3r commented Jun 17, 2016

thanks for sharing!

@luisdaher

This comment has been minimized.

Copy link

@luisdaher luisdaher commented Jun 29, 2016

Nice template! Thanks!

@neeraj9

This comment has been minimized.

Copy link

@neeraj9 neeraj9 commented Jul 30, 2016

Just what I was looking for. Thanks for sharing.

@whlsxl

This comment has been minimized.

Copy link

@whlsxl whlsxl commented Aug 3, 2016

Thanks!!!!

@nitish1402

This comment has been minimized.

Copy link

@nitish1402 nitish1402 commented Aug 4, 2016

Thank you

@idtyu

This comment has been minimized.

Copy link

@idtyu idtyu commented Aug 8, 2016

Thank you!

@lalitsingh198910

This comment has been minimized.

Copy link

@lalitsingh198910 lalitsingh198910 commented Aug 9, 2016

Thanks for the sharing.

@hanhdt

This comment has been minimized.

Copy link

@hanhdt hanhdt commented Aug 12, 2016

Thank you for sharing examples!

@ttruongatl

This comment has been minimized.

Copy link

@ttruongatl ttruongatl commented Aug 13, 2016

Thanks

@marcellodesales

This comment has been minimized.

Copy link

@marcellodesales marcellodesales commented Aug 17, 2016

Using it! ๐Ÿ‘

@k-schmidt

This comment has been minimized.

Copy link

@k-schmidt k-schmidt commented Aug 17, 2016

Using this for my API doc

@spabloramirez

This comment has been minimized.

Copy link

@spabloramirez spabloramirez commented Aug 26, 2016

fabulous!

@longtimeago

This comment has been minimized.

Copy link

@longtimeago longtimeago 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

@nmh0391 nmh0391 commented Oct 10, 2016

Simple yet elegant. Thanks!

@fsalehpour

This comment has been minimized.

Copy link

@fsalehpour fsalehpour commented Oct 15, 2016

Thanks for sharing.

@moiroca

This comment has been minimized.

Copy link

@moiroca moiroca commented Oct 26, 2016

Thanks!

@suvajit

This comment has been minimized.

Copy link

@suvajit suvajit commented Oct 29, 2016

Exactly what I was looking for. Good one. Thanks

@jethrolai

This comment has been minimized.

Copy link

@jethrolai jethrolai commented Nov 7, 2016

You can include the header section.

@DAC001

This comment has been minimized.

Copy link

@DAC001 DAC001 commented Nov 12, 2016

Thanks buddy! ๐Ÿ‘

@Otienoh

This comment has been minimized.

Copy link

@Otienoh Otienoh commented Nov 16, 2016

So useful, Thanks so MUCH

@edsu

This comment has been minimized.

Copy link

@edsu edsu 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

@egomez-eendlabs egomez-eendlabs commented Nov 22, 2016

Thanks for this, it's was very helpfull

@NickNaso

This comment has been minimized.

Copy link

@NickNaso NickNaso commented Dec 8, 2016

Thanks good example!

@shiqingjie

This comment has been minimized.

Copy link

@shiqingjie shiqingjie commented Dec 22, 2016

So good!

@anovanmaximuz

This comment has been minimized.

Copy link

@anovanmaximuz anovanmaximuz commented Jan 1, 2017

good

@aresowj

This comment has been minimized.

Copy link

@aresowj aresowj commented Jan 23, 2017

Very nice examples, thanks!

@jordanmkoncz

This comment has been minimized.

Copy link

@jordanmkoncz jordanmkoncz 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

@xmanemran xmanemran commented Feb 5, 2017

Thanks.

@Snehasispanigrahi

This comment has been minimized.

Copy link

@Snehasispanigrahi Snehasispanigrahi commented Mar 27, 2017

Thanks ๐Ÿ‘

@binzailani3136

This comment has been minimized.

Copy link

@binzailani3136 binzailani3136 commented Mar 28, 2017

PERFECT!

@aindong

This comment has been minimized.

Copy link

@aindong aindong commented Apr 18, 2017

Thank you so much!

@maciejmatu

This comment has been minimized.

Copy link

@maciejmatu maciejmatu 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

@sstrycker-zspace sstrycker-zspace commented Apr 28, 2017

Great!

@amixpal

This comment has been minimized.

Copy link

@amixpal amixpal commented May 4, 2017

Awesome !

@code-gems

This comment has been minimized.

Copy link

@code-gems code-gems commented May 9, 2017

thanks much. Very helpful

@cyrildewit

This comment has been minimized.

Copy link

@cyrildewit cyrildewit commented May 17, 2017

Thanks

@emaalouf

This comment has been minimized.

Copy link

@emaalouf emaalouf commented Jun 13, 2017

Thanks

@hanx11

This comment has been minimized.

Copy link

@hanx11 hanx11 commented Jun 15, 2017

Thanks, but can you give an example of rst?

@rajanjain

This comment has been minimized.

Copy link

@rajanjain rajanjain commented Jun 28, 2017

Good example. Helpful...

@Qolzam

This comment has been minimized.

Copy link

@Qolzam Qolzam commented Jul 22, 2017

Thank you so much. +1:

@toantd90

This comment has been minimized.

Copy link

@toantd90 toantd90 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

@naveeniq naveeniq commented Jul 26, 2017

Thanks for this great reference.

@prembhaskal

This comment has been minimized.

Copy link

@prembhaskal prembhaskal commented Jul 30, 2017

nice example. very helpful ๐Ÿ‘

@AshishBagdane

This comment has been minimized.

Copy link

@AshishBagdane AshishBagdane commented Aug 6, 2017

Thank You !

@FlomeWorld

This comment has been minimized.

Copy link

@FlomeWorld FlomeWorld commented Sep 8, 2017

nice !

@saledwin

This comment has been minimized.

Copy link

@saledwin saledwin commented Sep 13, 2017

Nice example. Thanks!

@wongzigii

This comment has been minimized.

Copy link

@wongzigii wongzigii commented Sep 18, 2017

Nice example. ๐Ÿ‘

@ecleipteon

This comment has been minimized.

Copy link

@ecleipteon ecleipteon commented Sep 24, 2017

Thank you a lot!

@yuda110

This comment has been minimized.

Copy link

@yuda110 yuda110 commented Oct 31, 2017

Thanks!

@MeTaLiKiD

This comment has been minimized.

Copy link

@MeTaLiKiD MeTaLiKiD commented Nov 16, 2017

Nice example, thanks

@keshav1990

This comment has been minimized.

Copy link

@keshav1990 keshav1990 commented Nov 24, 2017

nice example , thanks for sharing

@pourya2374

This comment has been minimized.

Copy link

@pourya2374 pourya2374 commented Jan 16, 2018

so nice

@tantq

This comment has been minimized.

Copy link

@tantq tantq commented Jan 19, 2018

Thank you so much

@mtm9999

This comment has been minimized.

Copy link

@mtm9999 mtm9999 commented Feb 19, 2018

Thanks!

@codeblooded

This comment has been minimized.

Copy link

@codeblooded codeblooded 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

@dotperinch dotperinch commented Feb 28, 2018

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

@psy21d

This comment has been minimized.

Copy link

@psy21d psy21d commented Mar 24, 2018

Okay, I really need this.

@MichaelCurrie

This comment has been minimized.

Copy link

@MichaelCurrie MichaelCurrie 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

@aleruete aleruete commented May 8, 2018

Thank You!

@airangel0120

This comment has been minimized.

Copy link

@airangel0120 airangel0120 commented May 14, 2018

thank you!

@ztchia

This comment has been minimized.

Copy link

@ztchia ztchia commented Jun 8, 2018

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

@dhaneshwarsingh

This comment has been minimized.

Copy link

@dhaneshwarsingh dhaneshwarsingh commented Jul 24, 2018

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

@chaimkut

This comment has been minimized.

Copy link

@chaimkut chaimkut 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

@599316527 599316527 commented Nov 9, 2018

How to specify request/response headers

@v4lerio

This comment has been minimized.

Copy link

@v4lerio v4lerio commented Jan 10, 2019

Thanks for sharing

@alberss

This comment has been minimized.

Copy link

@alberss alberss commented Feb 25, 2019

๐Ÿฅ‡ ๐Ÿ™ Thanks!

@bitfishxyz

This comment has been minimized.

Copy link

@bitfishxyz bitfishxyz commented Mar 12, 2019

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

@clombardi

This comment has been minimized.

Copy link

@clombardi clombardi 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

@Jaymo Jaymo commented Apr 25, 2019

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

@camilamiz

This comment has been minimized.

Copy link

@camilamiz camilamiz commented May 8, 2019

Thank you so much! Very useful!

@raulinoneto

This comment has been minimized.

Copy link

@raulinoneto raulinoneto commented May 10, 2019

Thank you!! I'll use it

@phungrk

This comment has been minimized.

Copy link

@phungrk phungrk commented May 24, 2019

Thank you!!

@KyleXID

This comment has been minimized.

Copy link

@KyleXID KyleXID commented Jun 24, 2019

Thank you for sharing !!!

@kkkumarkanike

This comment has been minimized.

Copy link

@kkkumarkanike kkkumarkanike commented Oct 15, 2019

shall I know where is the endpoint URL of GitHub API

@anibal21

This comment has been minimized.

Copy link

@anibal21 anibal21 commented Dec 27, 2019

Thanks!

@itsRealoj

This comment has been minimized.

Copy link

@itsRealoj itsRealoj commented Apr 30, 2020

Thanks a lot

@sangelesgu

This comment has been minimized.

Copy link

@sangelesgu sangelesgu commented May 27, 2020

Thanks! Amazing example!

@DeepakDG

This comment has been minimized.

Copy link

@DeepakDG DeepakDG commented Jun 13, 2020

This is what I was looking for..Thanks..Great work

@thirupathi-chintu

This comment has been minimized.

Copy link

@thirupathi-chintu thirupathi-chintu commented Oct 6, 2020

Awesome!

@Atlantisland

This comment has been minimized.

Copy link

@Atlantisland Atlantisland commented Oct 11, 2020

Thank you so much!

@ZmlAlex

This comment has been minimized.

Copy link

@ZmlAlex ZmlAlex commented Oct 19, 2020

Thanks!

@candidosales

This comment has been minimized.

Copy link

@candidosales candidosales commented Oct 23, 2020

Thanks!!

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.