Let's learn about client-server interaction over HTTP in more detail:

1. The client sends to the server a request that is basically a text document that consists of:
   • A verb (such as GET or POST ) that defines what action the server should perform,
   • Headers that define additional information about the request,
   • (Optional) body.
2. The server sends a response consisting of:
   • A status code,
   • Headers,
   • (Optional) body.

Now let's see what an HTTP request is like by deconstructing each of its 3 components:

• A verb (a.k.a. method) in an HTTP request expresses an action that needs to be taken with a resource. Although there are 39 possible HTTP verbs, many of them are downright esoteric. Most often you'll see these 5 verbs used:
  • GET: request a resource.
  • POST: create a resource.
  • PUT: update a resource.
  • PATCH: update a part of a resource.
  • DELETE: delete a resource.
• Request headers are metadata about a request written as key-value pairs. Some headers can apply both to requests and responses while others are only used with requests. The most popular HTTP headers are:
  • Content-Type: indicates the media type of a resource.
  • Content-Length: indicates the size of request body.
  • Authorization: proves to the server that the requesting client is authorized to make the request.
  • Accept: specifies what content types the requesting client understands.
  • Cookie: contains HTTP cookies previously received from the server. Cookies are small pieces of data that are used to carry state across HTTP requests that are otherwise stateless.
• An optional body of a request contains data associated with a request, such as the content of an HTML form passed with a POST request. However, content is invalid with some verbs, most notably with GET.

Any HTML response consists of the following parts:

• Status code that represents the result of processing a request. Status code is a number that is interpreted depending on what range if falls into:
  • 100-199: informational status. Rarely used.
  • 200-299: success status. Any status in this range confirms, in one way or another, that a request has been successfully executed.
  • 300-399: redirection status. Status in this range mean that the requested resource needs to be found somewhere else, such as in a cache or at a different URL.
  • 400-499: client errors. Status in this range signal some kind of error by the client: for example, errors in the query string, absent query string, or a nonexistent URL.
  • 500-599: server errors report that something went wrong on the server, and it's not the client's fault.
• Response headers are metadata about a response. They're similar to request headers, and in fact, a lot of headers can be used both in requests and in responses. Some response-specific headers include:
  • Expires: sets the date/time after which the response is considered outdated.
  • Set-Cookie: used to send a cookie from the server to the client, so that the client can send the cookie back to the server later.
• An optional body. A normal HTML page references CSS, JavaScript, XML, JSON, images and other kinds of resources, each requiring its own HTTP request.

Request and response are two individual calls. On the HTTP level, there's no connection between the client and the server that lasts. The responding web server is stateless: it's going to forget about the requester the moment it sends a response.

Approaches to distributed API design

Now that we've talked about networking and major protocols, let's have a quick overview of distributed API design approaches.

Historically, distributed computing started with RPC in the 1970s, then detoured into object-oriented approaches (such as CORBA and Java RMI) in the 1980s and 1990s. Early in the 21st century, approaches such as REST, XML-HTTP and SOAP emerged, and in 2010s the mix was extended with GraphQL and gRPC.

Let's look at RPC and REST, the two prominent approaches.

RPC

Before REST became popular, most APIs were built using XML-RPC or SOAP, which are two RPC-based HTTP APIs. So what exactly is RPC?

RPC (Remote Procedure Call) is just a way to call a function on a remote server. An RPC request represents an action and is structured like a function call in a programming language: there's a function name, function arguments, and possibly a return type. The server sees this call, does some internal processing, and then if a result is expected, it's going to send the resulting object back.

In contrast to REST, RPC isn't strict in HTTP verb usage: it only uses GET to fetch data and POST for everything else.

RPC introduces tight coupling between the client and the server: in addition to knowing about server resources, the client needs to know about the functions that can be called, the arguments that these functions need, and how to deal with the data coming back from these calls.

If the RPC server's API documentation is published, then it makes it clear to see what actions are available on the server. However, when client developers don't have access to either the underlying server code or API documentation, understanding proper RPC API usage can get really hard.

RPC is a good fit for APIs that are based on actions to take or processes to execute. It's also considered to be a better choice for non-public APIs or server-to-server interaction.

Here are examples of RPC calls:

1GET /readListOfEmployees?employeeId=25

1POST /modifyEmployee
2{
3"employeeId": "25",
4"position": "Regional Director"
5}

1POST /remoteDepartment
2{
3"departmentId": "3"
4}

REST

Today, REST (REpresentational State Transfer) is arguably the most discussed API architecture style, and certainly one of the most used.

REST can be defined as a stateless, layered and cacheable client-server architecture that operates with resources using a uniform command interface based on HTTP verbs. A resource is an entity (such as a document or file) that can be addressed with a unique resource locator (URL).

The strongest REST convention is to use a URL to express the resource you're working with, and a HTTP verb to express the action to take.

REST aims to follow HTTP semantics closely: a REST request is structured like an HTTP request. REST uses HTTP verbs - GET, POST, PUT, DELETE and PATCH - to reflect the intention of the action being taken:

1GET /employees/25

1PUT /employees/25
2{
3"position": "Regional Director"
4}

1DELETE /departments/3

Requests that the REST client sends to the server are stateless: every request occurs in complete isolation. When the client makes a request, it includes all information necessary for the server to process that request. The server never stores information from previous requests: if that information is critical, it's the client's responsibility to resend it with each subsequent request.

REST requires requests to be cacheable when possible, and caching is implemented using HTTP's native caching headers. This doesn't apply to all HTTP verbs though: while GET requests should be cacheable by default, POST requests can be made cacheable using headers, while POST and DELETE are not cacheable at all.

A REST API should be idempotent where possible - that is, making multiple identical requests should have the same effect as making a single request. This helps keep the API stable even when request duplication occurs due to network errors.

Compared to RPC, REST is loosely coupled: the server only has to expose resources that are being asked for, and there's a relatively small, well defined set of actions that can be done on those resources. The client only needs to know about the resources that the server exposes.

Since REST is designed to work with resources, it is a great fit when a domain can be easily described as a set of resources (as opposed to actions). When a domain is described this way, using standard HTTP methods in REST enables basic CRUD operations (create, read, update, delete) on all the domain's data.

REST is great for public-facing interfaces: because it's directly built upon the semantics of HTTP, it's intuitive for the consumer. On a related note, it's generally easier to keep REST APIs consistent and clean than it is with RPC style APIs.

REST has its own issues though:

• It's not a great fit for doing things that can't be directly mapped to resources. If you want to send an email, it's hard to do in a RESTful way as there's no resource to act upon (unless you have an "email" resource).
• If you have nested entities (for example, you want to get users along with their comments), you'll need to make multiple roundtrips to build up your state.

Choosing Between REST and RPC: A Guided Decision

When designing a distributed API, you may find yourself pondering whether to choose REST (Representational State Transfer) or RPC (Remote Procedure Call). Both have their unique attributes and best-use cases. Let's break down how to make this decision based on your specific needs.

1. When Your API is Mostly Actions

Prefer RPC

• How it works: RPC focuses on invoking remote procedures or actions, often representing functions or methods.
• Why choose this: If your API is primarily about performing specific actions or tasks, RPC is designed to accommodate that behavior.

2. When Your API is Mostly Manipulating Structured Data

Prefer REST

• How it works: REST revolves around manipulating resources, using standard HTTP methods like GET, POST, PUT, and DELETE.
• Why choose this: If your API deals mainly with structured data and adheres to the stateless and uniform interface principles, REST is the natural fit.

3. When Your API is a Mix of Both

It's OK to Use Both Styles

• How it works: You don't have to lock yourself into one paradigm. Combining REST and RPC can provide the flexibility to handle both actions and data manipulation.
• Why choose this: If your API requires the strengths of both REST and RPC, mixing the styles can offer a more nuanced and responsive design.

The choice between REST and RPC doesn't have to be a binary one. By understanding the nature of your API and what you want to achieve, you can make an informed decision that best aligns with your goals. Remember, being pragmatic and open to using both styles can sometimes lead to a more effective and adaptable API design.

Where to learn more?

• What happens when you type google.com into your browser and press Enter?
• RFC 1122: Requirements for Internet Hosts -- Communication Layers
• What are examples of TCP and UDP in real life?
• HTTP request methods
• HTTP headers
• Understanding RPC vs REST For HTTP APIs
• REST API tutorial
• Comparing SOAP vs REST APIs

One Pager Cheat Sheet

• We can learn about HTTP request and response by deconstructing each of its components, such as the verb (a.k.a. method) with associated headers and an optional body, and understanding web server behavior, which is stateless.
• An "Unauthorized" request error can occur when the client does not include an Authorization header in the HTTP request, resulting in an error with a status code in the range 400-499, indicating a client error.
• RPC and REST are two prominent approaches to distributed API design over the past few decades.
• RPC (Remote Procedure Call) is a way to call a function on a remote server, which uses GET to fetch data and POST for everything else, and is good fit for APIs that are based on actions.
• The RPC protocol uses POST for all calls that make updates to the server, while REST generally follows the conventions of using GET, PUT, PATCH, and DELETE for modifications.
• REST is an architecture style for creating stateless, cacheable, HTTP-semantic client-server APIs that enable CRUD operations on resources, expressed with unique URLs and HTTP verbs.
• No, REST and RPC are not interchangeable, as the HTTP verb used for each of them has a different purpose with regards to the type of operation.
• When deciding between RPC and REST for an API, consider if it's mostly actions or structured data - and if it's both, it's OK to use both styles!
• RPC APIs, such as PlaceOrder, are used to perform a certain action when a specific event occurs.