Introducing REST APIs

An API is the means by which a piece of code communicates with another piece of code.

Oct 27, 2021 - 22:53 Updated: Oct 28, 2021 - 15:26

0 186

Introducing REST APIs

An API is the means by which a piece of code communicates with another piece of code. You might have already written an API for your code or used one in your programs; for example, in Java libraries for collection, input/output, or streams that provide a variety of APIs to perform specific tasks.

Java's SDK APIs allow one part of a program to communicate with another part of a program. You can write a function and then expose it with public access modifiers so that other classes can use it. That function signature is an API for that class. However, APIs that are exposed using these classes or libraries only allow internal communication inside a single application or individual service. So, what happens when two or more applications (or services) want to communicate with each other? In other words, you would like to integrate two or more services. This is where system-wide APIs help us.

Historically, there were different ways to integrate one application with another – RPC, Simple Object Access Protocol (SOAP)-based services, and more. The integration of apps has become an integral part of software architectures, especially after the boom of the cloud and mobile phones. You now have social logins, such as Facebook, Google, and GitHub, which means you can develop your application even without writing an independent login module and get around security issues such as storing passwords in a secure way.

These social logins provide APIs using REST and GraphQL. Currently, REST is the most widely used, and it has become a standard for writing APIs for integration and web app consumption.

REST stands for REpresentational State Transfer, which is a style of software architecture. Web services that adhere to the REST style are called RESTful web services.

REST fundamentals

REST works on top of the HTTP protocol. Each URI works as an API resource. Therefore, we should use nouns as endpoints instead of verbs. RPC-style endpoints use verbs, for example, api/v1/getPersons. In comparison, in REST, this endpoint could be simply written as api/v1/persons. You must be wondering, then, how can we differentiate between the different actions performed on a REST resource? This is where HTTP methods help us. We can make our HTTP methods act as a verb, for example, GET, DELETE, POST (for creating), PUT (for modifying), and PATCH (for partial updating). We'll discuss this in more detail later. For now, the getPerson RPC-style endpoint is translated into GET api/v1/persons in REST.

The REST endpoint is a unique URI that represents a REST resource. For example, https://demo.app/api/v1/persons is a REST endpoint. Additionally, /api/v1/persons is the endpoint path and persons is the REST resource.

Here, there is client and server communication. Therefore, REST is based on the Client-Server concept. The client calls the REST API and the server responds with a response. REST allows a client (that is, a program, web service, or UI app) to talk to a remotely (or locally) running server (or web service) using HTTP requests and responses. The client sends to the web service with an API
command wrapped in an HTTP request to the web. This HTTP request may contain a payload (or input) in the form of query parameters, headers, or request bodies. The called web service responds with a success/failure indicator and the response data wrapped inside the HTTP response. The HTTP status code normally denotes the status, and the response body contains the response data. For example, an HTTP status code of 200 OK normally represents success.

From a REST perspective, an HTTP request is selfdescriptive and has enough context for the server to process it. Therefore, REST calls are stateless. States are either managed on the client side or on the server side. A REST API does not maintain its state. It only transfers states from the server to the client or vice versa. Therefore, it is called REpresentation State Transfer, or REST for short.

It also makes use of HTTP cache control, which makes REST APIs cacheable. Therefore, the client can also cache the representation (that is, the HTTP response) because every representation is self-descriptive.

The following is a list of key concepts in REST:

Resources and URIs
HTTP methods

A sample REST call in plain text looks similar to the following:

GET /licenses HTTP/1.1
Host: api.github.com

Here, the /licenses path denotes the licenses resource. GET is an HTTP method. 1.1 at the end of the first line denotes the HTTP protocol version. The second line shares the host to call.

GitHub responds with a JSON object. The status is 200 OK and the JSON object is wrapped in a response body, as follows: HTTP/1.1 200 OK.

date: Sun, 22 Sep 2020 18:01:22 GMT
content-type: application/json; charset=utf-8
server: GitHub.com
status: 200 OK
cache-control: public, max-age=60, s-maxage=60
vary: Accept, Accept-Encoding, Accept, X-Requested-With,
Accept-Encoding
etag: W/"3cbb5a2e38ac6fc92b3d798667e828c7e3584af278aa3
14f6eb1857bbf2593ba"
… 
Accept-Ranges: bytes
Content-Length: 2507
X-GitHub-Request-Id: 1C03:5C22:640347:81F9C5:5F70D372
[
{
"key": "agpl-3.0",
"name": "GNU Affero General Public License v3.0",
"spdx_id": "AGPL-3.0",
"url": "https://api.github.com/licenses/agpl-3.0",
"node_id": "MDc6TGljZW5zZTE="
},
{
"key": "apache-2.0",
"name": "Apache License 2.0",
"spdx_id": "Apache-2.0",
"url": "https://api.github.com/licenses/
apache-2.0",
"node_id": "MDc6TGljZW5zZTI="
},
…
]

If you take note of the third line in this response, it tells you the value of the content type. It is good practice to have JSON as a content type for both the request and the response.

Handling resources and URIs

Every document on the World Wide Web (WWW) is represented as a resource in terms of HTTP. This resource is represented as a URI, which is an endpoint that represents a unique resource on a server.

Roy Fielding states that a URI is known by many names – a WWW address, a Universal Document Identifier (UDI), a URI, a Uniform Resource Locator (URL), and a Uniform Resource Name (URN).

So, what is a URI? A URI is a string (that is, a sequence of characters) that identifies a resource by its location, name, or both (in the WWW world). There are two types of URIs – URLs and URNs.

URLs are widely used and even known to non-developer users. URLs are not only restricted to HTTP; in fact, they are also used for many other protocols such as FTP, JDBC, and MAILTO. Therefore, a URL is an identifier that identifies the network location of a resource. We will go into more detail in the later sections.

The URI syntax

The URI syntax is as follows:

scheme:[//authority]path[?query][#fragment]

As per the syntax, the following is a list of components of a URI:

Scheme: This refers to a non-empty sequence of characters followed by a colon (:). scheme starts with a letter and is followed by any combination of digits, letters, periods (.), hyphens (-), or plus characters (+). Scheme examples include HTTP, HTTPS, MAILTO, FILE, FTP, and more. URI schemes must be registered with the Internet Assigned Numbers Authority (IANA).
Authority: This is an optional field and is preceded by //. It consists of the following optional subfields:
- Userinfo: This is a subcomponent that might contain a username and a password, which are both optional.
- Host: This is a subcomponent containing either an IP address or a registered host or domain name.
- Port: This is an optional subcomponent that is followed by a colon (:).
Path: A path contains a sequence of segments separated by slash characters (/). In the preceding GitHub REST API example, /licenses is the path.
Query: This is an optional component and is preceded by a question mark (?). The query component contains a query string of non-hierarchical data. Each parameter is separated by an ampersand (&) in the query component and parameter values are assigned using an equals (=) operator.
Fragment: This is an optional field and is preceded by a hash (#). The fragment component includes a fragment identifier that gives direction to a secondary resource.

The following list contains examples of URIs:

www.example.com: This doesn't contain the scheme. It just contains the domain name. There is no port either, which means it points to the default port.
index.html: This contains no scheme nor authority. It only contains the path.
https://www.example.com/index.html: This contains the scheme, authority, and path.

Here are some examples of different scheme URIs:

mailto:support@example.com
telnet://192.168.0.1:23/
ldap://[2020:ab9::9]/c=AB?objectClass?obj

From a REST perspective, the path component of a URI is very important because it represents the resource path and your API endpoint paths are formed based on it. For example, take a look at the following: GET https://www.domain.com/api/v1/order/1

Here, /api/v1/order/1 represents the path, and GET represents the HTTP method.

URLs

If you look closely, most of the URI examples mentioned earlier can also be called URLs. A URI is an identifier; on the other hand, a URL is not only an identifier, but it also tells you how to get to it.

As per Request for Comments (RFC)-3986 on URIs (https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3986.html), the term URL refers to the subset of URIs that, in addition to identifying a resource, provide a means of locating the resource by describing its primary access mechanism (for example, its network "location").

A URL represents the full web address of a resource, including the protocol name (the scheme), the hostname port (in case the HTTP port is not 80; for HTTPS, the default port is 443), part of the authority component, the path, and optional query and fragment subcomponents.

URNs

URNs are not commonly used. They are also a type of URI that starts with a scheme – urn. The following URN example is directly taken from RFC-3986 for URIs (https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3986.html): urn:oasis:names:specification:docbook:dtd:xml:4.1.2

This example follows the "urn:" ":" syntax, where is the NAMESPACE IDENTIFIER, and is the Namespace-specific String. We are not going to use URNs in our REST implementation. However, you can read more about them at RFC-2141 (https://tools.ietf.org/html/rfc2141).

As per RFC-3986 on URIs (https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3986.html): The term URN has been used historically to refer to both URIs under the "urn" scheme RFC-2141, which are required to remain globally unique and persistent even when the resource ceases to exist or becomes unavailable, and to any other URI with the properties of a name.

Exploring HTTP methods and status codes

HTTP provides various HTTP methods. However, you are primarily going to use only five of them. To begin with, you want to have Create, Read, Update, and Delete (CRUD) operations associated with HTTP methods:

POST: Create or search
GET: Read
PUT: Update
DELETE: Delete
PATCH: Partial Update

Some organizations also provide the HEAD method for scenarios where you just want to retrieve the header responses from the REST endpoints. You can hit any GitHub API with the HEAD operation to retrieve only headers; for example, curl --head https://api.github.com/users.

REST has no such requirement that specifies which method should be used for which operation. However, widely used industry guidelines and practices suggest following certain rules.

Let's discuss each HTTP method in detail:

POST

The HTTP POST method is normally what you want to associate with creating resource operations. However, there are certain exceptions when you might want to use the POST method for read operations. However, it should be put into practice after a well-thought-out process. One such exception is the search operation where filter criteria have too many parameters that might cross the GET call's length limit.

A GET query string has a limit of 256 characters. Additionally, the GET HTTP method is limited to a maximum of 2,048 characters minus the number of characters in the actual path. On the other hand, the POST method is not limited by the size of the URL for submitting name and value pairs.

You may also want to use the POST method with HTTPS for a read call if the submitted input parameters contain any private or secure information.

For successful create operations, you can respond with the 201 Created status, and for successful search or read operations, you should use the 200 OK or 204 No Content status codes, although the call is made using the POST HTTP method.

For failed operations, REST responses may have different error status codes based on the error type, which we will look at later.

GET

The HTTP GET method is what you usually want to associate with read resource operations. Similarly, you must have observed the GitHub GET /licenses call that returns the available licenses in the GitHub system. Additionally, successful GET operations should be associated with the 200 OK status code if the response contains data, or 204 No Content if the response contains no data.

PUT

The HTTP PUT method is what you usually want to associate with update resource operations. Additionally, successful update operations should be associated with a 200 OK status code if the response contains data, or 204 No Content if the response contains no data. Some developers use the PUT HTTP method to replace existing resources. For example, GitHub API v3 uses PUT to replace the existing resource.

DELETE

The HTTP DELETE method is what you want to associate with delete resource operations. GitHub does not provide the DELETE operation on the licenses resource. However, if you assume it exists, it will certainly look very similar to DELETE /licenses/agpl-3.0. A successful delete call should delete the resource associate with the agpl-3.0 key. Additionally, successful DELETE operations should be associated with the 204 No Content status code.

PATCH

The HTTP PATCH method is what you want to associate with partial update resource operations. Additionally, successful PATCH operations should be associated with a 200 OK status code. PATCH is relatively new as compared to other HTTP operations. In fact, a few years ago, Spring did not have state-of-the-art support for this method for REST implementation due to the old Java HTTP library. However, currently, Spring provides built-in support for the PATCH method in REST implementation.