How to design a REST API

REST describes a standard way of creating HTTP APIs. The four common actions (view, create, edit, and delete) by a certain software can be map directly to HTTP verbs that are already implemented: GET, POST, PUT, DELETE.

How to name your resources

REST resources use a consistent naming scheme, and always a REST resource is accesible via an http url. When you are interacting with an API, you are almost always manipulating some sort of object. In REST terminology, this is called a Resource. Resources are always named in plural

/users

This is always used when referring to this collection of resources ("list all" and "add one" actions). When you are working with a specific resource, you add the ID to the URL.

/users/123

This URL is used when you want to "view", "edit", or "delete" the particular resource.

HTTP Status Codes

Another important part of a REST API is responding with the correct status code for the type of request that was made. When you make an HTTP request, the server will respond with a code which corresponds to whether or not the request was successful and how the client should proceed. There are four different levels of codes:

2xx = Success

3xx = Redirect

4xx = User error

5xx = Server error

API response

When a REST API resource is requested, the format can be requested as well. This is made using Content-type and Accept headers, so API should be designed to accept the content-types that later on will be allowed.