Skip to content

Instantly share code, notes, and snippets.

@iros
Created August 22, 2012 14:42
Show Gist options
  • Save iros/3426278 to your computer and use it in GitHub Desktop.
Save iros/3426278 to your computer and use it in GitHub Desktop.
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);
        }
      });
@599316527
Copy link

How to specify request/response headers

@v4lerio
Copy link

v4lerio commented Jan 10, 2019

Thanks for sharing

@piny4man
Copy link

🥇 🙏 Thanks!

@bitfishxyz
Copy link

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

@clombardi
Copy link

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

@Jaymo
Copy link

Jaymo commented Apr 25, 2019

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

@camilamiz
Copy link

Thank you so much! Very useful!

@raulinoneto
Copy link

Thank you!! I'll use it

@phungrk
Copy link

phungrk commented May 24, 2019

Thank you!!

@KyleXID
Copy link

KyleXID commented Jun 24, 2019

Thank you for sharing !!!

@kkkumarkanike
Copy link

shall I know where is the endpoint URL of GitHub API

@anibal21
Copy link

Thanks!

@itsRealoj
Copy link

Thanks a lot

@sangelesgu
Copy link

Thanks! Amazing example!

@DeepakDG
Copy link

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

@thirupathi-chintu
Copy link

Awesome!

@Atlantisland
Copy link

Thank you so much!

@ZmlAlex
Copy link

ZmlAlex commented Oct 19, 2020

Thanks!

@candidosales
Copy link

Thanks!!

@azagniotov
Copy link

azagniotov commented Mar 19, 2021

I got inspired by this Gist, so thank you, @iros!
Then I ended up creating something a-la Swagger-ish (maybe?) looking in Markdown using expandable sections, have a look:
https://gist.github.com/azagniotov/a4b16faf0febd12efbc6c3d7370383a6

or the actual API docs: https://stubby4j.com/docs/admin_portal.html#creating-newoverwriting-existing-stubs--proxy-configs

@zikrianbia
Copy link

Thank you

@uviigideon
Copy link

Great helpful! Thanks for share.

@vncsna
Copy link

vncsna commented Apr 30, 2021

Thanks for sharing

@sawaca96
Copy link

sawaca96 commented May 3, 2021

👍👍👍Thanks

@MonicaisHer
Copy link

Thank you very much ;)

@urmakgkg
Copy link

Thank you

@ShenShu2016
Copy link

thanks

@adeisbright
Copy link

Thank you for this

@earthkingman
Copy link

감사합니다

@gshyeon-testworks
Copy link

Nice format!

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