mirror of
https://github.com/twirl/The-API-Book.git
synced 2025-05-25 22:08:06 +02:00
proofreading
This commit is contained in:
parent
68ad84fdab
commit
652de8e87d
@ -1,8 +1,8 @@
|
||||
### [Extending through Abstracting][back-compat-abstracting-extending]
|
||||
|
||||
In the previous chapters, we have tried to outline theoretical rules and illustrate them with practical examples. However, understanding the principles of the change-proof API design requires practice above all things. An ability to anticipate future growth problems comes from a handful of grave mistakes once made. One cannot foresee everything but can develop a certain technical intuition.
|
||||
In the previous chapters, we have attempted to outline theoretical rules and illustrate them with practical examples. However, understanding the principles of designing change-proof APIs requires practice above all else. The ability to anticipate future growth problems comes from a handful of grave mistakes once made. While it is impossible to foresee everything, one can develop a certain technical intuition.
|
||||
|
||||
So, in the following chapters, we will try to probe [our study API](#api-design-annex) from the previous Section, testing its robustness from every possible viewpoint, thus carrying out some “variational analysis” of our interfaces. More specifically, we will apply a “What If?” question to every entity, as if we are to provide a possibility to write an alternate implementation of every piece of logic.
|
||||
Therefore, in the following chapters, we will test the robustness [our study API](#api-design-annex) from the previous Section, examining it from various perspectives to perform a “variational analysis” of our interfaces. More specifically, we will apply a “What If?” question to every entity, as if we are to provide a possibility to write an alternate implementation of every piece of logic.
|
||||
|
||||
**NB**. In our examples, the interfaces will be constructed in a manner allowing for dynamic real-time linking of different entities. In practice, such integrations usually imply writing an ad hoc server-side code in accordance with specific agreements made with specific partners. But for educational purposes, we will pursue more abstract and complicated ways. Dynamic real-time linking is more typical in complex program constructs like operating system APIs or embeddable libraries; giving educational examples based on such sophisticated systems would be too inconvenient.
|
||||
|
||||
|
@ -4,7 +4,7 @@ Before we proceed to discuss HTTP API design patterns, we feel obliged to clarif
|
||||
|
||||
What is “REST”? In 2000, Roy Fielding, one of the authors of the HTTP and URI specifications, published his doctoral dissertation titled “Architectural Styles and the Design of Network-based Software Architectures,” the fifth chapter of which was named “[Representational State Transfer (REST)](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm).”
|
||||
|
||||
As anyone can attest by reading this chapter, it features a very much abstract review of a distributed client-server architecture that is not bound to either HTTP or URL. Furthermore, it does not discuss any API design recommendations. In this chapter, Fielding methodically *enumerates restrictions* that any software engineer encounters when developing distributed client-server software. Here they are:
|
||||
As anyone can attest by reading this chapter, it features a very much abstract overview of a distributed client-server architecture that is not bound to either HTTP or URL. Furthermore, it does not discuss any API design recommendations. In this chapter, Fielding methodically *enumerates restrictions* that any software engineer encounters when developing distributed client-server software. Here they are:
|
||||
* The client and the server do not know how each of them is implemented
|
||||
* Sessions are stored on the client (the “stateless” constraint)
|
||||
* Data must be marked as cacheable or non-cacheable
|
||||
@ -40,4 +40,4 @@ Do we want to say that REST is a meaningful concept? Definitely not. We only aim
|
||||
|
||||
On one hand, thanks to the multitude of interpretations, the API developers have built a perhaps vague but useful view of “proper” HTTP API architecture. On the other hand, the lack of concrete definitions has made REST API one of the most “holywar”-inspiring topics, and these holywars are usually quite meaningless as the popular REST concept has nothing to do with the REST described in Fielding's dissertation (and even more so, with the REST described in Fielding's manifesto of 2008).
|
||||
|
||||
The terms “REST architectural style” and its derivative “REST API” will not be used in the following chapters since it makes no practical sense as we explained above. We referred to the constraints described by Fielding many times in the previous chapters because, let us emphasize it once more, it is impossible to develop distributed client-server APIs without taking them into account. However, HTTP API (meaning JSON-over-HTTP endpoints utilizing the semantics described in the HTTP and URL standards) as we will describe it in the following chapter aligns well with the “average” understanding of “REST / RESTful API” as per numerous tutorials on the Web.
|
||||
The terms “REST architectural style” and its derivative “REST API” will not be used in the following chapters since it makes no practical sense as we explained above. We referred to the constraints described by Fielding many times in the previous chapters because, let us emphasize it once more, it is impossible to develop distributed client-server APIs without taking them into account. However, HTTP APIs (meaning JSON-over-HTTP endpoints utilizing the semantics described in the HTTP and URL standards) as we will describe them in the following chapter align well with the “average” understanding of “REST / RESTful API” as per numerous tutorials on the Web.
|
@ -46,11 +46,11 @@ URLs are decomposed into sub-components, each of which is optional:
|
||||
* A host: a top-level address unit in the form of either a domain name or an IP address. A host might contain subdomains.
|
||||
* A port.
|
||||
* A path: a URL part between the host (including port) and the `?` or `#` symbols or the end of the line.
|
||||
* In practice, the path itself is usually decomposed into parts using the `/` symbol as a delimiter. However, the standard does not prescribe such decomposition or define any semantics for it.
|
||||
* The path itself is usually decomposed into parts using the `/` symbol as a delimiter. However, the standard does not define any semantics for it.
|
||||
* Two paths, one ending with `/` and one without it (for example, `/root/leaf` and `/root/leaf/`), are considered different paths according to the standard. Conversely, two URLs that differ only in trailing slashes in their paths are considered different as well. However, we are unaware of a single argument to differentiate such URLs in practice.
|
||||
* Paths may contain `.` and `..` parts, which are supposed to be interpreted similarly to analogous symbols in file paths (meaning that `/root/leaf`, `/root/./leaf`, and `/root/branch/../leaf` are equivalent). However, the standard again does not prescribe this.
|
||||
* Paths may contain `.` and `..` parts, which are supposed to be interpreted similarly to analogous symbols in file paths (meaning that `/root/leaf`, `/root/./leaf`, and `/root/branch/../leaf` are equivalent).
|
||||
* A query: a URL part between the `?` symbol and either `#` or the end of the line.
|
||||
* A query is usually decomposed into `key=value` pairs split by the `&` character. Again, the standard does not require this.
|
||||
* A query is usually decomposed into `key=value` pairs split by the `&` character. Again, the standard does not require this or define the semantics.
|
||||
* Nor does the standard imply any normalization of the ordering. URLs that differ only in the order of keys in the queries are considered different.
|
||||
* A fragment (also known as an anchor): a part of a URL that follows the `#` sign.
|
||||
* Fragments are usually treated as addresses within the requested document and because of that are often omitted by user agents while executing the request.
|
||||
|
Loading…
x
Reference in New Issue
Block a user