🪴 Сад Знаний

Search

SearchSearch

Pt.1 - How to Design a RESTful API Architecture From a Human-Language Spec – O’Reilly

Jan 15, 2025, 3 min read

Pt.1 - How to Design a RESTful API Architecture From a Human-Language Spec – O’Reilly

rw-book-cover

Metadata

Highlights

  • Although many programmers release uncreative APIs that merely expose database functions (the well-known CRUD operations of Create, Read, Update, Delete), useful APIs go beyond that and reflect the functions requested by the user, such as Reserve or Buy. They offer terms and processes that are intuitive to the programmer at the other end—including meaningful error status messages—and are structured to maximize efficiency. (View Highlight)

  • The process for you’ll learn in this article for designing a RESTful HTTP API architecture has two steps: (View Highlight)

  • Let’s review a few key concepts of RESTful APIs as we start reasoning about our own application. First of all, we need to think about the basic elements used in REST: (View Highlight)

  • It’s important to understand that REST is not a protocol, but an architectural style. It’s a set of rules and guidelines that define how a system should function. REST is not limited to HTTP, but in practice, when people talk about RESTful APIs, they are likely talking about APIs using the HTTP protocol. (View Highlight)

  • One of the main authors of HTTP is also the creator of REST. No wonder HTTP has parts that fit very well to these REST basic elements: (View Highlight)

  • Thus, to properly design our RESTful API we need to know really well the meaning of each HTTP method. What are the semantics behind each method? How should we use them? Let’s see: (View Highlight)

  • Besides that, we also need to care about which data from resources will be included in request and response bodies. For example, on a POST request for creation, the body needs to include the resource representation to be created. Another example, a GET response body needs to contain a resource representation, but a DELETE response body does not. (View Highlight)

  • Summarizing, here’s what we need to answer here to design our API: (View Highlight)

  • Which HTTP method maps to “Rent”? (View Highlight)

  • There is also another HTTP method used for updates: PATCH. We omitted it because it’s not often used and when it is, it’s used wrongly. A PATCH request should contain in its body the instructions to change a server resource. In other words, it carries a representation of changes to be applied at the resource, not the whole updated resource itself, like in PUT. That’s the difference between them. Those different representations reflect the difference between a partial and a full update. Most RESTful APIs accept both partial and full updates in PUT, with the representation being the resource, not the changes to the applied on it. That’s why PUT is more common than PATCH. (View Highlight)

  • We’ve seen that REST is made of resources, representations, and actions. We’ve also seen that resources are like nouns and actions are like verbs. So, identifying the nouns and verbs available at a system spec is a good way to start our spec to API process. (View Highlight)

📂 Articles | Последнее изменение: 23.11.2024 16:34

Graph View

Backlinks