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 commented Nov 25, 2014

Nice Example - Thanks for sharing

@sheffler

This comment has been minimized.

Copy link

sheffler commented Jan 26, 2015

It is nice. Thanks.

@ahuntcirruspath

This comment has been minimized.

Copy link

ahuntcirruspath commented Feb 13, 2015

Thank you!

@nisxiya

This comment has been minimized.

Copy link

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 commented Jun 29, 2015

Thanks.

@allergictoeng

This comment has been minimized.

Copy link

allergictoeng commented Sep 16, 2015

Thanks a lot

@yoonkwon

This comment has been minimized.

Copy link

yoonkwon commented Sep 25, 2015

Thank you! very good template!

@devHudi

This comment has been minimized.

Copy link

devHudi commented Oct 15, 2015

Thanks!

@zoldello

This comment has been minimized.

Copy link

zoldello commented Nov 5, 2015

Awesome++

@rafagomes

This comment has been minimized.

Copy link

rafagomes commented Nov 21, 2015

Nice!

@shridhaarchippaa

This comment has been minimized.

Copy link

shridhaarchippaa commented Nov 24, 2015

Thanks Iros for sharing. Nice example with formatting.

@vaananart

This comment has been minimized.

Copy link

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 commented Dec 11, 2015

Nice formatting dude

@IuryAlves

This comment has been minimized.

Copy link

IuryAlves commented Jan 11, 2016

Awesome!

@wnulilalbab

This comment has been minimized.

Copy link

wnulilalbab commented Feb 5, 2016

it's really nice, thanks for sharing

@stanislavromanov

This comment has been minimized.

Copy link

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 commented Mar 20, 2016

awesome ๐Ÿ‘

@zazapeta

This comment has been minimized.

Copy link

zazapeta commented Apr 14, 2016

thanx !

@yevgnenll

This comment has been minimized.

Copy link

yevgnenll commented Apr 22, 2016

fabulous!

@pradeeppdt

This comment has been minimized.

Copy link

pradeeppdt commented Apr 22, 2016

Awsome 5 Stars for a Basic API Doc Template

@twig2let

This comment has been minimized.

Copy link

twig2let commented Apr 28, 2016

Super!

@Nicholk24

This comment has been minimized.

Copy link

Nicholk24 commented May 17, 2016

Nice!

@Bharat9623925980

This comment has been minimized.

Copy link

Bharat9623925980 commented May 21, 2016

thanks for such a nice template

@saginadir

This comment has been minimized.

Copy link

saginadir commented May 25, 2016

Awesome ๐Ÿ‘

@uginm102

This comment has been minimized.

Copy link

uginm102 commented Jun 3, 2016

Great

@gbazilio

This comment has been minimized.

Copy link

gbazilio commented Jun 5, 2016

Nice!

@toymak3r

This comment has been minimized.

Copy link

toymak3r commented Jun 17, 2016

thanks for sharing!

@luisdaher

This comment has been minimized.

Copy link

luisdaher commented Jun 29, 2016

Nice template! Thanks!

@neeraj9

This comment has been minimized.

Copy link

neeraj9 commented Jul 30, 2016

Just what I was looking for. Thanks for sharing.

@whlsxl

This comment has been minimized.

Copy link

whlsxl commented Aug 3, 2016

Thanks!!!!

@nitish1402

This comment has been minimized.

Copy link

nitish1402 commented Aug 4, 2016

Thank you

@idtyu

This comment has been minimized.

Copy link

idtyu commented Aug 8, 2016

Thank you!

@lalitsingh198910

This comment has been minimized.

Copy link

lalitsingh198910 commented Aug 9, 2016

Thanks for the sharing.

@hanhdt

This comment has been minimized.

Copy link

hanhdt commented Aug 12, 2016

Thank you for sharing examples!

@ttruongatl

This comment has been minimized.

Copy link

ttruongatl commented Aug 13, 2016

Thanks

@marcellodesales

This comment has been minimized.

Copy link

marcellodesales commented Aug 17, 2016

Using it! ๐Ÿ‘

@k-schmidt

This comment has been minimized.

Copy link

k-schmidt commented Aug 17, 2016

Using this for my API doc

@spabloramirez

This comment has been minimized.

Copy link

spabloramirez commented Aug 26, 2016

fabulous!

@longtimeago

This comment has been minimized.

Copy link

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 commented Oct 10, 2016

Simple yet elegant. Thanks!

@fsalehpour

This comment has been minimized.

Copy link

fsalehpour commented Oct 15, 2016

Thanks for sharing.

@moiroca

This comment has been minimized.

Copy link

moiroca commented Oct 26, 2016

Thanks!

@suvajit

This comment has been minimized.

Copy link

suvajit commented Oct 29, 2016

Exactly what I was looking for. Good one. Thanks

@jethrolai

This comment has been minimized.

Copy link

jethrolai commented Nov 7, 2016

You can include the header section.

@DAC001

This comment has been minimized.

Copy link

DAC001 commented Nov 12, 2016

Thanks buddy! ๐Ÿ‘

@Otienoh

This comment has been minimized.

Copy link

Otienoh commented Nov 16, 2016

So useful, Thanks so MUCH

@edsu

This comment has been minimized.

Copy link

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 commented Nov 22, 2016

Thanks for this, it's was very helpfull

@NickNaso

This comment has been minimized.

Copy link

NickNaso commented Dec 8, 2016

Thanks good example!

@shiqingjie

This comment has been minimized.

Copy link

shiqingjie commented Dec 22, 2016

So good!

@anovanmaximuz

This comment has been minimized.

Copy link

anovanmaximuz commented Jan 1, 2017

good

@aresowj

This comment has been minimized.

Copy link

aresowj commented Jan 23, 2017

Very nice examples, thanks!

@jordanmkoncz

This comment has been minimized.

Copy link

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 commented Feb 5, 2017

Thanks.

@Snehasispanigrahi

This comment has been minimized.

Copy link

Snehasispanigrahi commented Mar 27, 2017

Thanks ๐Ÿ‘

@binzailani3136

This comment has been minimized.

Copy link

binzailani3136 commented Mar 28, 2017

PERFECT!

@aindong

This comment has been minimized.

Copy link

aindong commented Apr 18, 2017

Thank you so much!

@maciejmatu

This comment has been minimized.

Copy link

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 commented Apr 28, 2017

Great!

@amixpal

This comment has been minimized.

Copy link

amixpal commented May 4, 2017

Awesome !

@code-gems

This comment has been minimized.

Copy link

code-gems commented May 9, 2017

thanks much. Very helpful

@cyrildewit

This comment has been minimized.

Copy link

cyrildewit commented May 17, 2017

Thanks

@emaalouf

This comment has been minimized.

Copy link

emaalouf commented Jun 13, 2017

Thanks

@hanx11

This comment has been minimized.

Copy link

hanx11 commented Jun 15, 2017

Thanks, but can you give an example of rst?

@rajanjain

This comment has been minimized.

Copy link

rajanjain commented Jun 28, 2017

Good example. Helpful...

@Qolzam

This comment has been minimized.

Copy link

Qolzam commented Jul 22, 2017

Thank you so much. +1:

@toantd90

This comment has been minimized.

Copy link

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 commented Jul 26, 2017

Thanks for this great reference.

@prembhaskal

This comment has been minimized.

Copy link

prembhaskal commented Jul 30, 2017

nice example. very helpful ๐Ÿ‘

@AshishBagdane

This comment has been minimized.

Copy link

AshishBagdane commented Aug 6, 2017

Thank You !

@FlomeWorld

This comment has been minimized.

Copy link

FlomeWorld commented Sep 8, 2017

nice !

@saledwin

This comment has been minimized.

Copy link

saledwin commented Sep 13, 2017

Nice example. Thanks!

@wongzigii

This comment has been minimized.

Copy link

wongzigii commented Sep 18, 2017

Nice example. ๐Ÿ‘

@ecleipteon

This comment has been minimized.

Copy link

ecleipteon commented Sep 24, 2017

Thank you a lot!

@yuda110

This comment has been minimized.

Copy link

yuda110 commented Oct 31, 2017

Thanks!

@MeTaLiKiD

This comment has been minimized.

Copy link

MeTaLiKiD commented Nov 16, 2017

Nice example, thanks

@keshav1990

This comment has been minimized.

Copy link

keshav1990 commented Nov 24, 2017

nice example , thanks for sharing

@pourya2374

This comment has been minimized.

Copy link

pourya2374 commented Jan 16, 2018

so nice

@tantq

This comment has been minimized.

Copy link

tantq commented Jan 19, 2018

Thank you so much

@mtm9999

This comment has been minimized.

Copy link

mtm9999 commented Feb 19, 2018

Thanks!

@codeblooded

This comment has been minimized.

Copy link

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 commented Feb 28, 2018

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

@psy21d

This comment has been minimized.

Copy link

psy21d commented Mar 24, 2018

Okay, I really need this.

@MichaelCurrie

This comment has been minimized.

Copy link

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 commented May 8, 2018

Thank You!

@airangel0120

This comment has been minimized.

Copy link

airangel0120 commented May 14, 2018

thank you!

@ztchia

This comment has been minimized.

Copy link

ztchia commented Jun 8, 2018

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

@dhaneshwarsingh

This comment has been minimized.

Copy link

dhaneshwarsingh commented Jul 24, 2018

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

@chaimkut

This comment has been minimized.

Copy link

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 commented Nov 9, 2018

How to specify request/response headers

@v4lerio

This comment has been minimized.

Copy link

v4lerio commented Jan 10, 2019

Thanks for sharing

@alberss

This comment has been minimized.

Copy link

alberss commented Feb 25, 2019

๐Ÿฅ‡ ๐Ÿ™ Thanks!

@bitfishxyz

This comment has been minimized.

Copy link

bitfishxyz commented Mar 12, 2019

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

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.