Create a gist now

Instantly share code, notes, and snippets.

Embed
What would you like to do?
REST, RESTful API Quick Reference

REST, RESTful API Quick Reference

A good API is not just easy to use but also hard to misuse.

Ressources

  • Version your API

    • Path: /v1/users
    • Subdomain: api.v1.example.com/users
  • URI must be nouns, not verbs

    • /cars
    • /users
    • /books/{id}
  • GET requests must never alter system/resource state (GET is readonly)

  • All nouns are plurals

    • GET /users
    • DELETE /users/{id}
    • GET /users/{id}/reviews
    • POST /users/{id}/reviews
    • PUT /users/{id}/reviews/{rid}
  • Map relations by sub-resources

    • GET /users/{id}/reviews
    • PUT /users/{id}/reviews/{rid}
  • Allow for collections filtering, sorting and paging

    • GET /users?sort[]=-age&sort[]=+name
    • GET /users/{id}/reviews?published=1
    • GET /books?format[]=epub&format[]=mobi

Security

  • Allow only SSL (HTTPS) requests

Authentication

  • Use a standard and stateless authentication method:
    • API Key / Token (as part of the Authorization header)
    • Basic Authentication (Basic Auth)
  • The OAuth protocol is not stateless, because it requires the user to pass credentials one time, and then maintain state of the user’s authorization on the server side, these are not considerations of the underlying HTTP protocol.
  • If the authentication is unsuccessful, the status code 403 (Forbidden) is returned.

HTTP Header

  • Content-type: application/json

HTTP Methods

HTTP Verb HTTP Path CRUD Method Description Response codes
GET /users Index getUsers Used for retrieving a list of resources. 200 (OK), 404 (Not Found)
GET /users/{id} Read getUserById Used for retrieving a single resources. 200 (OK), 404 (Not Found)
POST /users Create insertUser Used for creating resources. 201 (Created), 404 (Not Found), 409 (Conflict) if resource already exists.
PUT /users/{id} Update updateUser Used for replacing the entire resources or collections. 200 (OK), 204 (No Content). 404 (Not Found)
PATCH /users/{id} Partial update updateUser Used for updating resources with partial data. 200 (OK), 204 (No Content), 404 (Not Found)
DELETE /users/{id} Delete deleteUser Used for deleting resources. 200 (OK), 404 (Not Found)

HTTP Status Codes

Status codes indicate the result of the HTTP request.

  • 1XX - informational
  • 2XX - success
  • 3XX - redirection
  • 4XX - client error
  • 5XX - server error

Return meaningful status codes:

Code Name What does it mean?
200 OK All right!
201 Created If resource was created successfully.
400 Bad Request 4xx Client Error
401 Unauthorized You are not logged in, e.g. using a valid access token
403 Forbidden You are authenticated but do not have access to what you are trying to do
404 Not found The resource you are requesting does not exist
405 Method not allowed The request type is not allowed, e.g. /users is a resource and POST /users is a valid action but PUT /users is not.
409 Conflict If resource already exists.
422 Unprocessable entity Validation failed. The request and the format is valid, however the request was unable to process. For instance when sent data does not pass validation tests.
500 Server error 5xx Server Error. An error occured on the server which was not the consumer's fault.

Error handling

General server error

Send a 500 Internal Server Error response.

HTTP Statuscode: 500

Content:

{
  "error": {
    "message": "Application Error"
  }
}

Content with error details:

{
  "error": {
    "code": 5001,
    "message": "Database connection failed"
  }
}

General client error

Sending invalid JSON will result in a 400 Bad Request response.

HTTP Statuscode: 400

Content:

{
  "error": {
    "code": 400,
    "message": "Problems parsing JSON"
  }
}

Validation errors

Sending invalid fields will result in a 422 Unprocessable Entity response.

HTTP Statuscode: 422

Content:

{
  "error": {
    "code": 422,
    "message": "Validation failed",
    "errors": [
      {
        "field": "email",
        "message": "Missing email"
      }
    ]
  }
}

Sample calls

jQuery

// Get base url
var url = $('head base').attr('href')

A GET request:

$.ajax({
    url: url + "users/1",
    type: "GET",
    cache: false,
    contentType: 'application/json',
    dataType: 'json'
}).done(function (data) {
    alert('Successfully');
    console.log(data);
}).fail(function (xhr) {
    var message = 'Server error';
    if (xhr.responseJSON && xhr.responseJSON.error.message) {
       message = xhr.responseJSON.error.message;
    }
    alert(message);
});

A POST request with payload:

var data = {
    username: "max",
    email: "max@example.com"
};

$.ajax({
    url: url + "users",
    type: "POST",
    contentType: 'application/json',
    dataType: 'json',
    data: JSON.stringify(data)
}).done(function (data) {
    alert("Success");
    console.log(data);
}).fail(function (xhr) {
    if (xhr.status === 422) {
        // Show validation errors
        var response = xhr.responseJSON;
        alert(response.error.message);
        $(response.error.errors).each(function (i, error) {
           console.log("Error in field [" + error.field + "]: " + error.message);
        });
    } else {
        var message = 'Server error';
        if (xhr.responseJSON && xhr.responseJSON.error.message) {
           message = xhr.responseJSON.error.message;
        }
        alert(message);
    }
});

Controllers

@TheNilesh

This comment has been minimized.

Show comment
Hide comment
@TheNilesh

TheNilesh May 25, 2018

409 Conflict If resource already exists.

409 can also be returned in case conflict in the state of the resource, that is through ETag or If-Not-Modified-Since header.

GET /users Index getUsers Used for retrieving a list of resources. 200 (OK), 404 (Not Found)

Instead of 404, an empty list should be returned when there are no resources. This will differentiate the cases resource URI is valid or not.

409 Conflict If resource already exists.

409 can also be returned in case conflict in the state of the resource, that is through ETag or If-Not-Modified-Since header.

GET /users Index getUsers Used for retrieving a list of resources. 200 (OK), 404 (Not Found)

Instead of 404, an empty list should be returned when there are no resources. This will differentiate the cases resource URI is valid or not.

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