Digest 2023–07–13
I’ve completed the “HTTP APIs & REST Architectural Principles” section of the book, and started the next (and last) one: “SDKs & UI Libraries”. In total, six new chapters published:
Chapter 38. Designing a Nomenclature of URLs. CRUD Operations
As we noted on several occasions in the previous chapters, neither the HTTP and URL standards nor REST architectural principles prescribe concrete semantics for the meaningful parts of a URL (notably, path fragments and key-value pairs in the query). The rules for organizing URLs in an HTTP API exist only to improve the API’s readability and consistency from the developers’ perspective. However, this doesn’t mean they are unimportant. Quite the opposite: URLs in HTTP APIs are a means of describing abstraction levels and entities’ responsibility areas. A well-designed API hierarchy should be reflected in a well-designed URL nomenclature.
Chapter 39. Working with HTTP API Errors
The examples of organizing HTTP APIs discussed in the previous chapters were mostly about “happy paths,” i.e., the direct path of working with an API in the absence of obstacles. It’s now time to talk about the opposite case: how HTTP APIs should work with errors and how the standard and the REST architectural principles can help us.
Chapter 40. Final Provisions and General Recommendations
Let’s summarize what was discussed in the previous chapters. To design a fine HTTP API one needs to:
- Describe a happy path, i.e. draw a diagram of all HTTP calls that occur during a normal work cycle of an application.
- Interpret every call as an operation executed on a resource and assemble a nomenclature of URLs and applicable methods accordingly.
- Enumerate errors that might occur during operation execution and determine paths to restore the application state for clients after receiving an error.
- Decide which functionality will be communicated at the HTTP protocol level, i.e., which standard protocol capabilities to use in conjunction with what tools and software and the extent of their usage.
- Develop a detailed specification regarding the aforementioned list points.
- Check yourselves: elaborate on paragraphs 1–3 to write pseudo-code for the application’s business logic in accordance with the specification, and evaluate the convenience, understandability and readability of your API.
Chapter 41. SDKs: Introduction
As we mentioned previously, the term “SDK” (which stands for “Software Development Kit”) lacks concrete meaning. The common understanding is that an SDK differs from an API as it provides both program interfaces and tools to work with them. This definition is hardly satisfactory as today any technology is likely to be provided with a bundled toolset.
However, there is a very specific narrow definition of an SDK: it is a client library that provides a high-level interface (usually a native one) to some underlying platform (such as a client-server API). Most often, we talk about libraries for mobile OSes or Web browsers that work on top of a general-purpose HTTP API.
Chapter 42: SDKs: Problems and Solutions
The first question we need to clarify about SDKs (let us reiterate that we use this term to denote a native client library that allows for working with a technology-agnostic underlying client-server API) is why SDKs exist in the first place. In other words, why is using “wrappers” more convenient for frontend developers than working with the underlying API directly?
Several reasons are obvious…
Chapter 43: Problems of Introducing UI Components
Introducing UI components to an SDK brings an additional dimension to an already complex setup comprising a low-level API and a client wrapper on top of it. Now both developers (who write the application) and end users (who use the application) interact with your API. This might not appear as a game changer at first glance; however, we assure you that it is. Involving an end-user has significant consequences from the API / SDK design point of view as it requires much more careful and elaborate program interfaces compared to a “pure” client-server API. Let us explain this statement with a concrete example.