Many web services use a REST architecture. REST stands for REpresentational State Transfer and simply describes the fact that on two systems (e.g. client and server), the same set of data can be represented differently, and in order to transfer that data (that is in a particular state) from one system to another, the two systems have to agree on
- how to represent the data when the data is being transferred between the two systems
- the transfer (communication) protocol used to transmit the data between the two systems.
For example, a user named Mike Tyson on a server may be represented by a document in a collection named User in a MongoDB database. Mike may also be represented by a Profile web page written in HTML in a client. They both contain the same data (e.g. name, email address, phone number), but the data is represented differently in the two systems. Now at any point in time, if the client wants to perform a CRUD (Create, Read, Update, Delete) operation on the data in the server, the two systems must agree on how to exchange the data.
Most RESTful web API protocols specify that JSON data is transmitted via HTTP. Fetch and express are just two examples of frameworks that simplify the communication between a clients and servers that use JSON over HTTP.
In order to make a web service efficient and scalable, developers often utilize RESTful web API design principals. Two main RESTful design principals are Platform Independence and Service Evolution. Platform Independence requires that any client, written in any programming language, running on any hardware, should be able to utilize the web service’s API, so long as they can communicate using the specified transfer protocol. Service Evolution requires that the continued development of the API be independent of the development of clients, and that all modifications to the API be backwards compatible (i.e. don’t break existing clients).
Other RESTful design principals include:
-
- REST APIs are designed around resources that can be accessed by the client.
- A resource has a URI (endpoint) that uniquely identifies the resource.
- REST APIs use a uniform interface.
- REST APIs use a stateless request model. This implies that each request is independent and the server does not maintain transient state information between requests.
Before we can begin implementing the API server we need to define the specifications for each endpoint. Each endpoint specification must contain the following:
-
- A HTTP Method (we’ll use GET, POST, PATCH, and DELETE).
- A URI (a path specifying a resource). Since resources are nouns, URIs should only contain nouns.
- Response status codes and messages
The following must also be documented in an endpoint specification, if utilized:
-
- A list of authorization tokens required in the Request’s headers
- A list of parameters in the URL
- A list of query strings in the URI and whether or not they are required
- Information about the properties in the body of request (name, type, required or not, default value if not required, constraints)
© 2024, Eric McGregor. All rights reserved. Unauthorized use, distribution and/or duplication of this material without express and written permission from the author is strictly prohibited.