Documenting your REST API

API.md

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

EXAMPLE.md

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

How to specify request/response headers

Thanks for sharing

🥇 🙏 Thanks!

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

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

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

Thank you so much! Very useful!

Thank you!! I'll use it

Thank you!!

Thank you for sharing !!!

shall I know where is the endpoint URL of GitHub API

Thanks!

Thanks a lot

Thanks! Amazing example!

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

Awesome!

Thank you so much!

Thanks!

Thanks!!

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

Thank you

Great helpful! Thanks for share.

Thanks for sharing

👍👍👍Thanks

Thank you very much ;)

Thank you

thanks

Thank you for this

감사합니다

Nice format!