concept server in category api

This is an excerpt from Manning's book Irresistible APIs: Designing web APIs that developers will love. Login to get full access to this book.

Figure 1.4. The basic interactions with an API are direct connections with the back-end server or servers, and a well-defined interaction with clients on the front end. This allows for countless frontend applications, whether mobile, website desktop, or system integrations, without changes to the back-end servers.

Similarly, HTTP is a well-known protocol used to drive the web traffic browsers generate. A web API is a system where clients use a defined interface to interact with a web server via the HTTP protocol; this can be an internal or an external system. To understand how this works in the context of a browser, when you type an address into the browser’s address bar, you’re asking that browser to retrieve a unique resource, like reaching a phone number. The browser asks the server for the information associated with that identifier, and it’s returned and formatted for you to view in the window. Web API clients make similar calls to read and write to the system, but the responses are formatted for programs to process instead of for browsers to display. One of the best-known APIs is Twitter, whose APIs are open to third-party developers, allowing those developers to create applications that integrate directly with Twitter. I discuss HTTP in detail in chapter 4.

Once you’re using a protocol, it’s important to have a well-described format for the messages that are sent through that protocol. What does a request look like? What response can be expected? To help you understand what needs to be communicated via the transactions between client and server, the requests and responses being sent over HTTP, I’ll bring these questions back into the real world. To support the needs of a computer system, a RESTful web API must support creating, reading, updating, and deleting items on the platform. Figure 1.5 describes how a web API works, comparing it to a real-world resource (an iced tea ordered at a coffee shop).

To make this clearer, let’s go back to my iced tea example. When I walk into a Starbucks in Barcelona, Spain, the cashier may greet me in English or Spanish. Depending on how I respond, the rest of the conversation will be in the language I choose. In this case, I (representing the client) expressed my preference for English by speaking in English, and the cashier will respond in kind if possible. When you indicate to your browser what your preferred language is, it will send a header along with requests to indicate this preference to the server. If the server is able to provide the response in the requested language, that’s what it should do.

Headers, then, are for context about the entire transaction. Common items passed in a request via headers include language preference, response format preference, authorization information, and compression preference. Table 4.10 shows common headers for requests, with a description of how each one is processed by the server to determine what response to send back.

Table 4.10. Common request headers

Header	Example value	Meaning
Accept	Text/html, application/json	The client’s preferred format for the response body. Browsers tend to prefer text/html, which is a human-friendly format. Applications using an API are likely to request JSON, which is structured in a machine-parseable way. This can be a list, and if so, the list is parsed in priority order: the first entry is the most desired format, all the way down to the last one (which frequently uses */* to indicate “whatever might be left”).
Accept-Language	en-US	The preferred written language for the response. This is most often used by browsers indicating the language the user has specified as a preference.
User-Agent	Mozilla/5.0	This header tells the server what kind of client is making the request. This is an important header because sometimes responses or JavaScript actions are performed differently for different browsers. This is used less frequently for this purpose by API clients, but it’s a friendly practice to send a consistent user-agent for the server to use when determining how to send the information back.
Content-Length	<size of the content body>	When sending a PUT or POST, this can be sent so the server can verify that the request body wasn’t truncated on the way to the server.
Content-Type	application/json	When a content body is sent, the client can indicate to the server what the format is for that content in order to help the server respond to the request correctly.

Each individual request from the client to the server needs to indicate the action it wants the server to take. To create a fully functional system, it needs to be able to create, read, update, and delete (CRUD), as shown in figure 4.3.

Figure 4.4. This is a human version of the programmatic transaction that follows. The interaction between the people demonstrates exactly how transactions work. As you can see, all the requests and responses between the client and the server map directly to an easy-to-understand interaction between people.

This is an excerpt from Manning's book The Design of Web APIs. Login to get full access to this book.

When a social network backend receives a photo and message, it might store the photo on the server’s filesystem and store the message and the photo identifier (to retrieve the actual file later) in a database. It could also process the photo using some homemade facial recognition algorithm to detect if it contains any friends of yours before storing the photo. That’s one possibility—a single application handling everything for another solitary application. Let’s consider something different, as shown in figure 1.4.

What happens when a consumer wants to complete the goal get product? Or, more specifically, what happens when they want to get detailed information about a product with the ID P123 from the products catalog using the REST Shopping API? Consumers have to communicate with the server hosting the API using the HTTP protocol, as shown in figure 3.2.

Figure 3.2 A REST API call using the HTTP protocol

Because this goal is represented by GET /products/{productId}, the consumer has to send a GET /products/P123 HTTP request to the Shopping API server. In reply, the server returns an HTTP response containing 200 OK, followed by the requested product’s information. (Note that this HTTP exchange has been simplified in order to focus only on the elements that matter to us.)

The request is composed of the GET HTTP method and the /products/P123 path. The path is an address identifying a resource on the server; in this case, the P123 product in products. The HTTP method indicates what the consumer wants to do with this resource: GET means that they want to retrieve the resource. From a functional perspective, such a request means something like, “Hi, can I have the information on the product whose ID is P123?” But from the HTTP protocol’s perspective, it means, “Hi, can I have the resource identified by the /products/P123 path?”