REST APIs
APIs follow a concept known as REST (REpresentational State Transfer). REST is not a technology, protocol, or specification but just a design pattern (or convention) that all APIs follow to make it easy for client programs to use the API. An API that is accessed over the internet using the HTTP/HTTPS protocol (the same one used by web browsers and servers), which is also referred to as a Web API.
The format in which data is exchanged when using APIs also needs to be standardized. Extended Markup Language (XML) was the first widely used format, which is now being slowly superseded by JSON (JavaScript Object Notation).
REST uses the concept of resources and resource methods. A resource is a specific entity that is managed by the database and a resource method is what the client calls to manage a resource. The term method is used interchangeably with function.
Generally, all applications work with data. They receive data as input, process the data, send processed data back as output and store data. Data management has four primary actions, often referred to as CRUD.
- CREATE: creates and adds new data to the database.
- READ: reads the data existing in the database.
- UPDATE: updates or modifies the data existing in the database.
- DELETE: it deletes data from the database.
REST defines some standard API methods that are used by all web and mobile applications. There are nine methods, but the four that are used for CRUD operations are:
- GET: The GET method is used to retrieve resources from the database.
- POST: The POST method is used to add new resources to the database.
- PUT: The PUT method is used to modify existing resources in the database.
- DELETE: The DELETE method is used to delete existing resources in the database.
The REST design guidelines suggest resource methods aligned with these four operations. Resource methods are very similar to the URLs you would type in your browser to access a website or a web application.
REST method examples:
| REST URL | Method Type | Function |
|---|---|---|
| https://api.example.com/v1 (opens in a new tab) | GET | This is the base endpoint and generally returns some details about the API only to indicate that the API is working fine. |
| https://api.example.com/v1/customers (opens in a new tab) | GET | A resource being acted upon (customer) is added to the end of the endpoint. This method will return all customers from the database. |
| https://api.example.com/v1/customers (opens in a new tab) | POST | The same URL but with a POST method type will add a customer (with values passed in the body of the API method call) to the database. |
| https://api.example.com/v1/customers/:id (opens in a new tab) | GET | The URL with an identifier at the end will return a customer with the matching identifier. |
| https://api.example.com/v1/customers/:id (opens in a new tab) | PUT | The URL with an identifier at the end but a PUT method type will update the customer with the matching identifier. |
| https://api.example.com/v1/customers/:id (opens in a new tab) | DELETE | The URL with an identifier at the end but a DELETE method type will delete the customer with the matching identifier. |
API method calls are structured such that you can send parameters in the URL as above, or in the header or body of the method. Header data ususally includes metadata for the request and authentication data. The body data is the request data; for example, when sending a POST request to create a new resource its attribute values will be sent in the body, usually in JSON or XML format.
REST API services can be developed and deployed using many technology stacks and programming languages. For web and smartphone apps one of the more popular stacks is Node.JS and Express.