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

This comment has been minimized.

Show comment Hide comment
@donlovett

donlovett Nov 25, 2014

Nice Example - Thanks for sharing

Nice Example - Thanks for sharing

@sheffler

This comment has been minimized.

Show comment Hide comment
@sheffler

sheffler Jan 26, 2015

It is nice. Thanks.

It is nice. Thanks.

@ahuntcirruspath

This comment has been minimized.

Show comment Hide comment
@ahuntcirruspath

ahuntcirruspath Feb 13, 2015

Thank you!

Thank you!

@nisxiya

This comment has been minimized.

Show comment Hide comment
@nisxiya

nisxiya May 25, 2015

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

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.

Show comment Hide comment
@leyafo

leyafo Jun 29, 2015

Thanks.

leyafo commented Jun 29, 2015

Thanks.

@allergictoeng

This comment has been minimized.

Show comment Hide comment
@allergictoeng

allergictoeng Sep 16, 2015

Thanks a lot

Thanks a lot

@yoonkwon

This comment has been minimized.

Show comment Hide comment
@yoonkwon

yoonkwon Sep 25, 2015

Thank you! very good template!

Thank you! very good template!

@devHudi

This comment has been minimized.

Show comment Hide comment
@devHudi

devHudi Oct 15, 2015

Thanks!

devHudi commented Oct 15, 2015

Thanks!

@zoldello

This comment has been minimized.

Show comment Hide comment
@zoldello

zoldello Nov 5, 2015

Awesome++

zoldello commented Nov 5, 2015

Awesome++

@rafagomes

This comment has been minimized.

Show comment Hide comment
@rafagomes

rafagomes Nov 21, 2015

Nice!

Nice!

@shridhaarchippaa

This comment has been minimized.

Show comment Hide comment
@shridhaarchippaa

shridhaarchippaa Nov 24, 2015

Thanks Iros for sharing. Nice example with formatting.

Thanks Iros for sharing. Nice example with formatting.

@vaananart

This comment has been minimized.

Show comment Hide comment
@vaananart

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

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.

Show comment Hide comment
@ardha2008

ardha2008 Dec 11, 2015

Nice formatting dude

Nice formatting dude

@IuryAlves

This comment has been minimized.

Show comment Hide comment
@IuryAlves

IuryAlves Jan 11, 2016

Awesome!

Awesome!

@wnulilalbab

This comment has been minimized.

Show comment Hide comment
@wnulilalbab

wnulilalbab Feb 5, 2016

it's really nice, thanks for sharing

it's really nice, thanks for sharing

@stanislavromanov

This comment has been minimized.

Show comment Hide comment
@stanislavromanov

stanislavromanov 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

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.

Show comment Hide comment
@webhacking

webhacking Mar 20, 2016

awesome πŸ‘

awesome πŸ‘

@zazapeta

This comment has been minimized.

Show comment Hide comment
@zazapeta

zazapeta Apr 14, 2016

thanx !

thanx !

@yevgnenll

This comment has been minimized.

Show comment Hide comment
@yevgnenll

yevgnenll Apr 22, 2016

fabulous!

fabulous!

@pradeeppdt

This comment has been minimized.

Show comment Hide comment
@pradeeppdt

pradeeppdt Apr 22, 2016

Awsome 5 Stars for a Basic API Doc Template

Awsome 5 Stars for a Basic API Doc Template

@twig2let

This comment has been minimized.

Show comment Hide comment
@twig2let

twig2let Apr 28, 2016

Super!

Super!

@Nicholk24

This comment has been minimized.

Show comment Hide comment
@Nicholk24

Nicholk24 May 17, 2016

Nice!

Nice!

@Bharat9623925980

This comment has been minimized.

Show comment Hide comment
@Bharat9623925980

Bharat9623925980 May 21, 2016

thanks for such a nice template

thanks for such a nice template

@saginadir

This comment has been minimized.

Show comment Hide comment
@saginadir

saginadir May 25, 2016

Awesome πŸ‘

Awesome πŸ‘

@uginm102

This comment has been minimized.

Show comment Hide comment
@uginm102

uginm102 Jun 3, 2016

Great

uginm102 commented Jun 3, 2016

Great

@gbazilio

This comment has been minimized.

Show comment Hide comment
@gbazilio

gbazilio Jun 5, 2016

Nice!

gbazilio commented Jun 5, 2016

Nice!

@toymak3r

This comment has been minimized.

Show comment Hide comment
@toymak3r

toymak3r Jun 17, 2016

thanks for sharing!

thanks for sharing!

@luisdaher

This comment has been minimized.

Show comment Hide comment
@luisdaher

luisdaher Jun 29, 2016

Nice template! Thanks!

Nice template! Thanks!

@neeraj9

This comment has been minimized.

Show comment Hide comment
@neeraj9

neeraj9 Jul 30, 2016

Just what I was looking for. Thanks for sharing.

neeraj9 commented Jul 30, 2016

Just what I was looking for. Thanks for sharing.

@whlsxl

This comment has been minimized.

Show comment Hide comment
@whlsxl

whlsxl Aug 3, 2016

Thanks!!!!

whlsxl commented Aug 3, 2016

Thanks!!!!

@nitish1402

This comment has been minimized.

Show comment Hide comment
@nitish1402

nitish1402 Aug 4, 2016

Thank you

Thank you

@idtyu

This comment has been minimized.

Show comment Hide comment
@idtyu

idtyu Aug 8, 2016

Thank you!

idtyu commented Aug 8, 2016

Thank you!

@lalitsingh198910

This comment has been minimized.

Show comment Hide comment
@lalitsingh198910

lalitsingh198910 Aug 9, 2016

Thanks for the sharing.

Thanks for the sharing.

@hanhdt

This comment has been minimized.

Show comment Hide comment
@hanhdt

hanhdt Aug 12, 2016

Thank you for sharing examples!

hanhdt commented Aug 12, 2016

Thank you for sharing examples!

@thanhtruong0315

This comment has been minimized.

Show comment Hide comment
@thanhtruong0315

thanhtruong0315 Aug 13, 2016

Thanks

Thanks

@marcellodesales

This comment has been minimized.

Show comment Hide comment
@marcellodesales

marcellodesales Aug 17, 2016

Using it! πŸ‘

Using it! πŸ‘

@k-schmidt

This comment has been minimized.

Show comment Hide comment
@k-schmidt

k-schmidt Aug 17, 2016

Using this for my API doc

Using this for my API doc

@spabloramirez

This comment has been minimized.

Show comment Hide comment
@spabloramirez

spabloramirez Aug 26, 2016

fabulous!

fabulous!

@longtimeago

This comment has been minimized.

Show comment Hide comment
@longtimeago

longtimeago 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 :)

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.

Show comment Hide comment
@nmh0391

nmh0391 Oct 10, 2016

Simple yet elegant. Thanks!

nmh0391 commented Oct 10, 2016

Simple yet elegant. Thanks!

@fsalehpour

This comment has been minimized.

Show comment Hide comment
@fsalehpour

fsalehpour Oct 15, 2016

Thanks for sharing.

Thanks for sharing.

@moiroca

This comment has been minimized.

Show comment Hide comment
@moiroca

moiroca Oct 26, 2016

Thanks!

moiroca commented Oct 26, 2016

Thanks!

@suvajit

This comment has been minimized.

Show comment Hide comment
@suvajit

suvajit Oct 29, 2016

Exactly what I was looking for. Good one. Thanks

suvajit commented Oct 29, 2016

Exactly what I was looking for. Good one. Thanks

@jethrolai

This comment has been minimized.

Show comment Hide comment
@jethrolai

jethrolai Nov 7, 2016

You can include the header section.

You can include the header section.

@DAC001

This comment has been minimized.

Show comment Hide comment
@DAC001

DAC001 Nov 12, 2016

Thanks buddy! πŸ‘

DAC001 commented Nov 12, 2016

Thanks buddy! πŸ‘

@Otienoh

This comment has been minimized.

Show comment Hide comment
@Otienoh

Otienoh Nov 16, 2016

So useful, Thanks so MUCH

Otienoh commented Nov 16, 2016

So useful, Thanks so MUCH

@edsu

This comment has been minimized.

Show comment Hide comment
@edsu

edsu Nov 18, 2016

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

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.

Show comment Hide comment
@egomez-eendlabs

egomez-eendlabs Nov 22, 2016

Thanks for this, it's was very helpfull

Thanks for this, it's was very helpfull

@NickNaso

This comment has been minimized.

Show comment Hide comment
@NickNaso

NickNaso Dec 8, 2016

Thanks good example!

NickNaso commented Dec 8, 2016

Thanks good example!

@shiqingjie

This comment has been minimized.

Show comment Hide comment
@shiqingjie

shiqingjie Dec 22, 2016

So good!

So good!

@anovanmaximuz

This comment has been minimized.

Show comment Hide comment
@anovanmaximuz

anovanmaximuz Jan 1, 2017

good

good

@aresowj

This comment has been minimized.

Show comment Hide comment
@aresowj

aresowj Jan 23, 2017

Very nice examples, thanks!

aresowj commented Jan 23, 2017

Very nice examples, thanks!

@jordanmkoncz

This comment has been minimized.

Show comment Hide comment
@jordanmkoncz

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

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.

Show comment Hide comment
@xmanemran

xmanemran Feb 5, 2017

Thanks.

Thanks.

@Snehasispanigrahi

This comment has been minimized.

Show comment Hide comment
@Snehasispanigrahi

Snehasispanigrahi Mar 27, 2017

Thanks πŸ‘

Thanks πŸ‘

@binzailani3136

This comment has been minimized.

Show comment Hide comment
@binzailani3136

binzailani3136 Mar 28, 2017

PERFECT!

PERFECT!

@aindong

This comment has been minimized.

Show comment Hide comment
@aindong

aindong Apr 18, 2017

Thank you so much!

aindong commented Apr 18, 2017

Thank you so much!

@maciejmatu

This comment has been minimized.

Show comment Hide comment
@maciejmatu

maciejmatu 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

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.

Show comment Hide comment
@sstrycker-zspace

sstrycker-zspace Apr 28, 2017

Great!

Great!

@amixpal

This comment has been minimized.

Show comment Hide comment
@amixpal

amixpal May 4, 2017

Awesome !

amixpal commented May 4, 2017

Awesome !

@code-gems

This comment has been minimized.

Show comment Hide comment
@code-gems

code-gems May 9, 2017

thanks much. Very helpful

thanks much. Very helpful

@cyrildewit

This comment has been minimized.

Show comment Hide comment
@cyrildewit

cyrildewit May 17, 2017

Thanks

Thanks

@emaalouf

This comment has been minimized.

Show comment Hide comment
@emaalouf

emaalouf Jun 13, 2017

Thanks

Thanks

@hanx11

This comment has been minimized.

Show comment Hide comment
@hanx11

hanx11 Jun 15, 2017

Thanks, but can you give an example of rst?

hanx11 commented Jun 15, 2017

Thanks, but can you give an example of rst?

@rajanjain

This comment has been minimized.

Show comment Hide comment
@rajanjain

rajanjain Jun 28, 2017

Good example. Helpful...

Good example. Helpful...

@Qolzam

This comment has been minimized.

Show comment Hide comment
@Qolzam

Qolzam Jul 22, 2017

Thank you so much. +1:

Qolzam commented Jul 22, 2017

Thank you so much. +1:

@toantd90

This comment has been minimized.

Show comment Hide comment
@toantd90

toantd90 Jul 26, 2017

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

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

@naveeniq

This comment has been minimized.

Show comment Hide comment
@naveeniq

naveeniq Jul 26, 2017

Thanks for this great reference.

Thanks for this great reference.

@prembhaskal

This comment has been minimized.

Show comment Hide comment
@prembhaskal

prembhaskal Jul 30, 2017

nice example. very helpful πŸ‘

nice example. very helpful πŸ‘

@AshishBagdane

This comment has been minimized.

Show comment Hide comment
@AshishBagdane

AshishBagdane Aug 6, 2017

Thank You !

Thank You !

@FlomeWorld

This comment has been minimized.

Show comment Hide comment
@FlomeWorld

FlomeWorld Sep 8, 2017

nice !

nice !

@saledwin

This comment has been minimized.

Show comment Hide comment
@saledwin

saledwin Sep 13, 2017

Nice example. Thanks!

saledwin commented Sep 13, 2017

Nice example. Thanks!

@wongzigii

This comment has been minimized.

Show comment Hide comment
@wongzigii

wongzigii Sep 18, 2017

Nice example. πŸ‘

Nice example. πŸ‘

@ecleipteon

This comment has been minimized.

Show comment Hide comment
@ecleipteon

ecleipteon Sep 24, 2017

Thank you a lot!

Thank you a lot!

@yuda110

This comment has been minimized.

Show comment Hide comment
@yuda110

yuda110 Oct 31, 2017

Thanks!

yuda110 commented Oct 31, 2017

Thanks!

@MeTaLiKiD

This comment has been minimized.

Show comment Hide comment
@MeTaLiKiD

MeTaLiKiD Nov 16, 2017

Nice example, thanks

Nice example, thanks

@keshav1990

This comment has been minimized.

Show comment Hide comment
@keshav1990

keshav1990 Nov 24, 2017

nice example , thanks for sharing

nice example , thanks for sharing

@pourya2374

This comment has been minimized.

Show comment Hide comment
@pourya2374

pourya2374 Jan 16, 2018

so nice

so nice

@tantq

This comment has been minimized.

Show comment Hide comment
@tantq

tantq Jan 19, 2018

Thank you so much

tantq commented Jan 19, 2018

Thank you so much

@mtm9999

This comment has been minimized.

Show comment Hide comment
@mtm9999

mtm9999 Feb 19, 2018

Thanks!

mtm9999 commented Feb 19, 2018

Thanks!

@codeblooded

This comment has been minimized.

Show comment Hide comment
@codeblooded

codeblooded Feb 21, 2018

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

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

@dotperinch

This comment has been minimized.

Show comment Hide comment
@dotperinch

dotperinch Feb 28, 2018

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

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

@psy21d

This comment has been minimized.

Show comment Hide comment
@psy21d

psy21d Mar 24, 2018

Okay, I really need this.

psy21d commented Mar 24, 2018

Okay, I really need this.

@MichaelCurrie

This comment has been minimized.

Show comment Hide comment
@MichaelCurrie

MichaelCurrie 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);
}});

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.

Show comment Hide comment
@aleruete

aleruete May 8, 2018

Thank You!

aleruete commented May 8, 2018

Thank You!

@airangel0120

This comment has been minimized.

Show comment Hide comment
@airangel0120

airangel0120 May 14, 2018

thank you!

thank you!

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