Text SMS is a tool that allows you to schedule a SMS text to anywhere in the world

 

The name of your API call
Example : Show All Users

 

  • Note: try to use verbs that match both request type (fetching vs modifying) and plurality (one vs multiple.)
  • Note: Also add additional info here such as a description, if need be.

 

URL

 

The URL structure (path only, no root url)
/users or /users/:id or /users?id=:id

 

  • For fixed urls: /users or /photos
  • For urls with parameters in them: /users/:id or /photos/:photo_id or /users?id=:id

 

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.

Required:
id=[integer]
example: id=12

Optional
photo_id=[alphanumeric]
example: photo_id=2345kj3

 

DATA PARAMS

 

If making a post request, what should the body payload look like? This is a good time to document your various data constraints too.
Example:

{u : 
{   email : [string],
    name : [string],
    current_password : [alphanumeric]
    password : [alphanumeric],
    password_confirmation : [alphanumeric]}}

Example:

{u : 
{   email : "john@smith.com",
    name : "John",
    current_password : "apassw0rd"
    password : "anewpassw0rd",
    password_confirmation : "anewpassw0rd"}}

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 call-backs should expect!
Example:
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 listed here. It might seem repetitive, but it helps prevent assumptions from being made where they shouldn’t be.
Example:
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.

$.ajax({url: "/users", dataType: "json",
  data : {u: {id : 12, email : "john@smith.com"}},
  type : "PUT",
  success : function(r) {console.log(r);}});

 

NOTES

 

This is where all uncertainties, commentary, discussion, etc… can go. I recommend time-stamping and identifying oneself when leaving comments here.