From e9f6495c0a30848f37409f2cd1c2a3cf29b0afc1 Mon Sep 17 00:00:00 2001 From: Sergey Konstantinov Date: Mon, 5 Jun 2023 23:42:41 +0300 Subject: [PATCH] fresh build --- docs/API.en.epub | Bin 1231540 -> 1231429 bytes docs/API.en.html | 71 ++++++++++++++++++++++---------------------- docs/API.en.pdf | Bin 8157288 -> 8154793 bytes docs/API.ru.epub | Bin 1340884 -> 1340729 bytes docs/API.ru.html | 11 ++++--- docs/API.ru.pdf | Bin 7942540 -> 7941086 bytes docs/v1/API.en.epub | Bin 1158768 -> 1158763 bytes docs/v1/API.en.html | 36 +++++++++++----------- docs/v1/API.en.pdf | Bin 7059259 -> 7059269 bytes docs/v1/API.ru.epub | Bin 1235188 -> 1235182 bytes docs/v1/API.ru.pdf | Bin 7336008 -> 7336008 bytes 11 files changed, 58 insertions(+), 60 deletions(-) diff --git a/docs/API.en.epub b/docs/API.en.epub index 35c797fafcdac7bd43aefc56cc941fedbff6b74d..d7e947ecc23a5189070fa23335f442805201ff44 100644 GIT binary patch delta 38686 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 diff --git a/docs/API.en.html b/docs/API.en.html index 7e471b3..798526b 100644 --- a/docs/API.en.html +++ b/docs/API.en.html @@ -3772,7 +3772,7 @@ X-Idempotency-Token: <token>

Finally, there is a third aspect to consider — the “canyon” you are crossing over with a bridge of your API. Developers write code that is executed in an environment beyond your control, and it evolves. New versions of operating systems, browsers, protocols, and programming language SDKs emerge. New standards are being developed and new arrangements are made, some of which are backward-incompatible, and there is nothing that can be done about that.

Older platform versions contribute to fragmentation just like older app versions as developers (including the API developers) struggle to support older platforms. At the same time, users face challenges with platform updates. In many cases, they are unable to update their devices to newer platform versions since newer platform versions require newer devices.

The most challenging aspect here is that not only does incremental progress, in the form of new platforms and protocols, necessitate changes to the API, but also the vulgar influence of trends. Several years ago realistic 3D icons were popular, but since then, public taste has changed in favor of flat and abstract ones. UI component developers had to follow the fashion, rebuilding their libraries by either shipping new icons or replacing the old ones. Similarly, the current trend of integrating the “night mode” feature has become widespread, demanding changes in a wide range of APIs.

-

Backwards-Compatible Specifications

+

Backward-Compatible Specifications

In the case of the API-first approach, the backward compatibility problem adds another dimension: the specification and code generation based on it. It becomes possible to break backward compatibility without breaking the spec (for example, by introducing eventual consistency instead of strict consistency) — and vice versa, modify the spec in a backward-incompatible manner without changing anything in the protocol and therefore not affecting existing integrations at all (for example, by replacing additionalProperties: false with true in OpenAPI).

The question of whether two specification versions are backward-compatible or not belongs to a gray zone, as specification standards themselves do not define this. Generally speaking, the statement “specification change is backward-compatible” is equivalent to “any client code written or generated based on the previous version of the spec continues to work correctly after the API vendor releases the new API version implementing the new version of the spec.” Practically speaking, following this definition seems quite unrealistic for two reasons: it is impossible to learn the behavior of every piece of code-generating software out there (for instance, it's rather hard to say whether code generated based on a specification that includes the parameter additionalProperties: false will still function properly if the server starts returning additional fields).

Thus, using IDLs to describe APIs with all the advantages they undeniably bring to the field, leads to having one aspect of the technology drift problem: the IDL version and, more importantly, versions of helper software based on it, are constantly and sometimes unpredictably evolving. If an API vendor employs the “code-first” approach, meaning that the spec is generated based on the actual API code, the occurrence of backward-incompatible changes in the server code — spec — code-generated SDK — client app chain is only a matter of time.

@@ -3815,8 +3815,8 @@ X-Idempotency-Token: <token>

Of course, preserving minor versions indefinitely is not possible (partly because of security and compliance issues that tend to accumulate). However, providing such access for a reasonable period of time is considered a hygienic norm for popular APIs.

Chapter 27. On the Waterline of the Iceberg 

-

Before we start talking about the extensible API design, we should discuss the hygienic minimum. A huge number of problems would have never happened if API vendors had paid more attention to marking their area of responsibility.

-

Provide a Minimal Amount of Functionality

+

Before we start talking about extensible API design, we should discuss the hygienic minimum. A huge number of problems would have never happened if API vendors had paid more attention to marking their area of responsibility.

+
1. Provide a Minimal Amount of Functionality

At any moment in its lifetime, your API is like an iceberg: it comprises an observable (i.e., documented) part and a hidden one, undocumented. If the API is designed properly, these two parts correspond to each other just like the above-water and under-water parts of a real iceberg do, i.e. one to ten. Why so? Because of two obvious reasons.

  • @@ -3826,25 +3826,24 @@ X-Idempotency-Token: <token>

    Revoking the API functionality causes losses. If you've promised to provide some functionality, you will have to do so “forever” (until this API version's maintenance period is over). Pronouncing some functionality deprecated is a tricky thing, potentially alienating your customers.

-

Rule #1 is the simplest: if some functionality might be withheld — then never expose it until you really need to. It might be reformulated like that: every entity, every field, and every public API method is a product decision. There must be solid product reasons why some functionality is exposed.

-
1. Avoid Gray Zones and Ambiguities
-

Your obligations to maintain some functionality must be stated as clearly as possible. Especially regarding those environments and platforms where no native capability to restrict access to undocumented functionality exists. Unfortunately, developers tend to consider some private features they found to be eligible for use, thus presuming the API vendor shall maintain them intact. Policy on such “findings” must be articulated explicitly. At the very least, in case of such non-authorized usage of undocumented functionality, you might refer to the docs and be in your own rights in the eyes of the community.

+

A rule of thumb is very simple: if some functionality might be withheld — then never expose it until you really need to. It might be reformulated like this: every entity, every field, and every public API method is a product decision. There must be solid product reasons why some functionality is exposed.

+
2. Avoid Gray Zones and Ambiguities
+

Your obligations to maintain some functionality must be stated as clearly as possible, especially regarding those environments and platforms where no native capability to restrict access to undocumented functionality exists. Unfortunately, developers tend to consider some private features they found to be eligible for use, thus presuming the API vendor shall maintain them intact. The policy on such “findings” must be articulated explicitly. At the very least, in the case of such non-authorized usage of undocumented functionality, you might refer to the docs and be within your rights in the eyes of the community.

However, API developers often legitimize such gray zones themselves, for example, by:

    -
  • returning undocumented fields in endpoints responses;
    • +
  • returning undocumented fields in endpoint responses;
  • using private functionality in code samples — in the docs, while responding to support messages, in conference talks, etc.

One cannot make a partial commitment. Either you guarantee this code will always work or do not slip the slightest note such functionality exists.

-
2. Codify Implicit Agreements
-

The third principle is much less obvious. Pay close attention to the code which you're suggesting developers to develop: are there any conventions that you consider evident, but never wrote them down?

+
3. Codify Implicit Agreements
+

The third principle is much less obvious. Pay close attention to the code that you're suggesting developers write: are there any conventions that you consider self-evident but never wrote down?

Example #1. Let's take a look at this order processing SDK example:

// Creates an order
 let order = api.createOrder();
 // Returns the order status
 let status = api.getStatus(order.id);
-

Let's imagine that you're struggling with scaling your service, and at some point moved to the asynchronous replication of the database. This would lead to the situation when querying for the order status right after the order creation might return 404 if an asynchronous replica hasn't got the update yet. In fact, thus we abandon a strict consistency policy in a favor of an eventual one.

-

What would be the result? The code above will stop working. A user creates an order, then tries to get its status — but gets the error. It's very hard to predict what approach developers would implement to tackle this error. Probably, they would not expect this to happen at all.

+

Let's imagine that you're struggling with scaling your service, and at some point switched to eventual consistency, as we discussed in the corresponding chapter. What would be the result? The code above will stop working. A user creates an order, then tries to get its status but receives an error instead. It's very hard to predict what approach developers would implement to tackle this error. They probably would not expect this to happen at all.

You may say something like, “But we've never promised strict consistency in the first place” — and that is obviously not true. You may say that if, and only if, you have really described the eventual consistency in the createOrder docs, and all your SDK examples look like this:

let order = api.createOrder();
 let status;
@@ -3862,8 +3861,8 @@ if (status) {
     …
 }
-

We presume we may skip the explanations why such code must never be written under any circumstances. If you're really providing a non-strictly consistent API, then either the createOrder operation must be asynchronous and return the result when all replicas are synchronized, or the retry policy must be hidden inside the getStatus operation implementation.

-

If you failed to describe the eventual consistency in the first place, then you simply couldn't make these changes in the API. You will effectively break backward compatibility, which will lead to huge problems with your customers' apps, intensified by the fact they can't be simply reproduced by QA engineers.

+

We presume we may skip the explanations of why such code must never be written under any circumstances. If you're really providing a non-strictly consistent API, then either the createOrder operation must be asynchronous and return the result when all replicas are synchronized, or the retry policy must be hidden inside the getStatus operation implementation.

+

If you failed to describe the eventual consistency in the first place, then you simply couldn't make these changes in the API. You will effectively break backward compatibility, which will lead to huge problems with your customers' apps, intensified by the fact that they can't be simply reproduced by QA engineers.

Example #2. Take a look at the following code:

let resolve;
 let promise = new Promise(
@@ -3873,9 +3872,9 @@ let promise = new Promise(
 );
 resolve();
-

This code presumes that the callback function passed to a new Promise will be executed synchronously, and the resolve variable will be initialized before the resolve() function call is executed. But this assumption is based on nothing: there are no clues indicating the new Promise constructor executes the callback function synchronously.

-

Of course, the developers of the language standard can afford such tricks; but you as an API developer cannot. You must at least document this behavior and make the signatures point to it; actually, the best practice is to avoid such conventions, since they are simply unobvious while reading the code. And of course, under no circumstances dare you change this behavior to an asynchronous one.

-

Example #3. Imagine you're providing animations API, which includes two independent functions:

+

This code presumes that the callback function passed to a new Promise will be executed synchronously, and the resolve variable will be initialized before the resolve() function call is executed. But this assumption is based on nothing: there are no clues indicating that the new Promise constructor executes the callback function synchronously.

+

Of course, the developers of the language standard can afford such tricks; but you as an API developer cannot. You must at least document this behavior and make the signatures point to it. Actually, the best practice is to avoid such conventions since they are simply not obvious when reading the code. And of course, under no circumstances dare you change this behavior to an asynchronous one.

+

Example #3. Imagine you're providing an animations API, which includes two independent functions:

// Animates object's width,
 // beginning with the first value, 
 // ending with the second
@@ -3888,8 +3887,8 @@ object.observe(
   'widthchange', observerFunction
 );
-

A question arises: how frequently and at what time fractions the observerFunction will be called? Let's assume in the first SDK version we emulated step-by-step animation at 10 frames per second. Then the observerFunction will be called 10 times, getting values '140px', '180px', etc., up to '500px'. But then, in a new API version, we have switched to implementing both functions atop of a system's native functionality — and so you simply don't know, when and how frequently the observerFunction will be called.

-

Just changing call frequency might result in making some code dysfunctional — for example, if the callback function makes some complex calculations, and no throttling is implemented since developers just relied on your SDK's built-in throttling. And if the observerFunction ceases to be called when exactly '500px' is reached because of some system algorithms specifics, some code will be broken beyond any doubt.

+

A question arises: how frequently and at what time fractions will the observerFunction be called? Let's assume in the first SDK version we emulated step-by-step animation at 10 frames per second. Then the observerFunction will be called 10 times, getting values '140px', '180px', etc., up to '500px'. But then, in a new API version, we have switched to implementing both functions atop the operating system's native functionality. Therefore, you simply don't know when and how frequently the observerFunction will be called.

+

Just changing the call frequency might result in making some code dysfunctional. For example, if the callback function performs some complex calculations and no throttling is implemented because developers relied on your SDK's built-in throttling. Additionally, if the observerFunction ceases to be called exactly when the '500px' value is reached due to system algorithm specifics, some code will be broken beyond any doubt.

In this example, you should document the concrete contract (how often the observer function is called) and stick to it even if the underlying technology is changed.

Example #4. Imagine that customer orders are passing through a specific pipeline:

GET /v1/orders/{id}/events/history
@@ -3914,16 +3913,16 @@ object.observe(
   }
 ]}
-

Suppose at some moment we decided to allow trustworthy clients to get their coffee in advance before the payment is confirmed. So an order will jump straight to "preparing_started" or even "ready" without a "payment_approved" event being emitted. It might appear to you that this modification is backwards-compatible since you've never really promised any specific event order being maintained, but it is not.

-

Let's assume that a developer (probably, your company's business partner) wrote some code implementing some valuable business procedures, for example, gathering income and expenses analytics. It's quite logical to expect this code operates a state machine, which switches from one state to another depending on getting (or getting not) specific events. This analytical code will be broken if the event order changes. In the best-case scenario, a developer will get some exceptions and will have to cope with the error's cause; in the worst case, partners will operate wrong statistics for an indefinite period of time until they find the issue.

-

A proper decision would be, first, documenting the event order and the allowed states; second, continuing generating the "payment_approved" event before the "preparing_started" one (since you're making a decision to prepare that order, so you're in fact approving the payment) and add extended payment information.

+

Suppose at some moment we decided to allow trustworthy clients to get their coffee in advance before the payment is confirmed. So an order will jump straight to "preparing_started" or even "ready" without a "payment_approved" event being emitted. It might appear to you that this modification is backward-compatible since you've never really promised any specific event order being maintained, but it is not.

+

Let's assume that a developer (probably your company's business partner) wrote some code implementing some valuable business procedures, for example, gathering income and expenses analytics. It's quite logical to expect this code operates a state machine that switches from one state to another depending on specific events. This analytical code will be broken if the event order changes. In the best-case scenario, a developer will get some exceptions and will have to cope with the error's cause. In the worst case, partners will operate the incorrect statistics for an indefinite period of time until they find the issue.

+

A proper decision would be, first, documenting the event order and the allowed states; second, continuing to generate the "payment_approved" event before the "preparing_started" one (since you're making a decision to prepare that order, so you're in fact approving the payment) and add extended payment information.

This example leads us to the last rule.

-
3. Product Logic Must Be Backwards-Compatible as Well
-

State transition graph, event order, possible causes of status changes — such critical things must be documented. However, not every piece of business logic might be defined in a form of a programmatical contract; some cannot be represented in a machine-readable form at all.

-

Imagine that one day you start to take phone calls. A client may contact the call center to cancel an order. You might even make this functionality technically backwards-compatible, introducing new fields to the “order” entity. But the end-user might simply know the number, and call it even if the app wasn't suggesting anything like that. Partner's business analytical code might be broken likewise, or start displaying weather on Mars since it was written knowing nothing about the possibility of canceling orders somehow in circumvention of the partner's systems.

-

A technically correct decision would be to add a “canceling via call center allowed” parameter to the order creation function. Conversely, call center operators might only cancel those orders which were created with this flag set. But that would be a bad decision from a product point of view as it's quite unobvious to users that they can cancel some orders by phone and can't cancel others. The only “good” decision in this situation is to foresee the possibility of external order cancellations in the first place. If you haven't foreseen it, your only option is the “Serenity Notepad” to be discussed in the last chapter of this Section.

Chapter 28. Extending through Abstracting 

-

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.

-

So, in the following chapters, we will try to probe our study API 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.

+
4. Product Logic Must Be Backward-Compatible as Well
+

State transition graph, event order, possible causes of status changes, etc. — such critical things must be documented. However, not every piece of business logic can be defined in the form of a programmable contract; some cannot be represented in a machine-readable form at all.

+

Imagine that one day you start taking phone calls. A client may contact the call center to cancel an order. You might even make this functionality technically backward-compatible by introducing new fields to the “order” entity. But the end-user might simply know the number and call it even if the app wasn't suggesting anything like that. The partner's business analytical code might be broken as well or start displaying weather on Mars since it was written without knowing about the possibility of canceling orders in circumvention of the partner's systems.

+

A technically correct decision would be to add a “canceling via call center allowed” parameter to the order creation function. Conversely, call center operators might only cancel those orders that were created with this flag set. But that would be a bad decision from a product point of view because it is not obvious to users that they can cancel some orders by phone and not others. The only “good” decision in this situation is to foresee the possibility of external order cancellations in the first place. If you haven't foreseen it, your only option is the “Serenity Notepad” that will be discussed in the last chapter of this Section.

Chapter 28. Extending through Abstracting 

+

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.

+

Therefore, in the following chapters, we will test the robustness our study API 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.

Let's start with the basics. Imagine that we haven't exposed any other functionality but searching for offers and making orders, thus providing an API of two methods: POST /offers/search and POST /orders.

Let us make the next logical step there and suppose that partners will wish to dynamically plug their own coffee machines (operating some previously unknown types of API) into our platform. To allow doing so, we have to negotiate a callback format that would allow us to call partners' APIs and expose two new endpoints providing the following capabilities:

@@ -4454,7 +4453,7 @@ ProgramContext.dispatch = (action) => {

There are obvious local problems with this approach (like the inconsistency in functions' behavior, or the bugs which were not found while testing the code), but also a bigger one: your API might be simply unusable if a developer tries any non-mainstream approach, because of performance issues, bugs, instability, etc., as the API developers themselves never tried to use this public interface for anything important.

NB. The perfect example of avoiding this anti-pattern is the development of compilers; usually, the next compiler's version is compiled with the previous compiler's version.

5. Keep a Notepad
-

Whatever tips and tricks described in the previous chapters you use, it's often quite probable that you can't do anything to prevent API inconsistencies from piling up. It's possible to reduce the speed of this stockpiling, foresee some problems, and have some interface durability reserved for future use. But one can't foresee everything. At this stage, many developers tend to make some rash decisions, e.g., releasing a backwards-incompatible minor version to fix some design flaws.

+

Whatever tips and tricks described in the previous chapters you use, it's often quite probable that you can't do anything to prevent API inconsistencies from piling up. It's possible to reduce the speed of this stockpiling, foresee some problems, and have some interface durability reserved for future use. But one can't foresee everything. At this stage, many developers tend to make some rash decisions, e.g., releasing a backward-incompatible minor version to fix some design flaws.

We highly recommend never doing that. Remember that the API is also a multiplier of your mistakes. What we recommend is to keep a serenity notepad — to write down the lessons learned, and not to forget to apply this knowledge when a new major API version is released.

[Work in Progress] Section IV. The HTTP API & REST

Chapter 33. On the HTTP API Concept and Terminology 

The problem of designing HTTP APIs is unfortunately one of the most “holywar”-inspiring issues. On one hand, it is one of the most popular technologies but, on the other hand, it is quite complex and difficult to comprehend due to the large and fragmented standard split into many RFCs. As a result, the HTTP specification is doomed to be poorly understood and imperfectly interpreted by millions of software engineers and thousands of textbook writers. Therefore, before proceeding to the useful part of this Section, we must clarify exactly what we are going to discuss.

It has somehow happened that the entire modern network stack used for developing client-server APIs has been unified in two important points. One of them is the Internet Protocol Suite, which comprises the IP protocol as a base and an additional layer on top of it in the form of either the TCP or UDP protocol. Today, alternatives to the TCP/IP stack are used for a very limited subset of engineering tasks.

@@ -4479,7 +4478,7 @@ ProgramContext.dispatch = (action) => {

We will refer to such APIs as “HTTP APIs” or “JSON-over-HTTP APIs.” We understand that this is a loose interpretation of the term, but we prefer to live with that rather than using the phrase “JSON-over-HTTP endpoints utilizing the semantics described in the HTTP and URL standards” each time.

Chapter 34. The REST Myth 

Before we proceed to discuss HTTP API design patterns, we feel obliged to clarify one more important terminological issue. Often, an API matching the description we gave in the previous chapter is called a “REST API” or a “RESTful API.” In this Section, we don't use any of these terms as it makes no practical sense.

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).”

-

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)
    • @@ -4510,7 +4509,7 @@ ProgramContext.dispatch = (action) => {

    We have no idea why, out of all the overviews of abstract network-based software architecture, Fielding's concept gained such popularity. It is obvious that Fielding's theory, reflected in the minds of millions of software developers, became a genuine engineering subculture. By reducing the REST idea to the HTTP protocol and the URL standard, the chimera of a “RESTful API” was born, of which nobody knows the definition.

    Do we want to say that REST is a meaningful concept? Definitely not. We only aimed to explain that it allows for quite a broad range of interpretations, which is simultaneously its main power and its main weakness.

    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.

    Chapter 35. Components of an HTTP Request and Their Semantics 

    +

    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.

    Chapter 35. Components of an HTTP Request and Their Semantics 

    The third important exercise we must conduct is to describe the format of an HTTP request and response and explain the basic concepts. Many of these may seem obvious to the reader. However, the situation is that even the basic knowledge we require to move further is scattered across vast and fragmented documentation, causing even experienced developers to struggle with some nuances. Below, we will try to compile a structured overview that is sufficient to design HTTP APIs.

    To describe the semantics and formats, we will refer to the brand-new RFC 9110, which replaces no fewer than nine previous specifications dealing with different aspects of the technology. However, a significant volume of additional functionality is still covered by separate standards. In particular, the HTTP caching principles are described in the standalone RFC 9111, while the popular PATCH method is omitted in the main RFC and is regulated by RFC 5789.

    An HTTP request consists of (1) applying a specific verb to a URL, stating (2) the protocol version, (3) additional meta-information in headers, and (4) optionally, some content (request body):

    @@ -4547,14 +4546,14 @@ Content-Type: application/json
  • 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.
    • @@ -5080,7 +5079,7 @@ X-ApiName-Partner-Id: <partner_id>
    2. Requesting an Additional Authentication Factor

    As both static and behavioral analyses are heuristic, it's highly desirable to not make decisions based solely on their outcome but rather ask the suspicious users to additionally prove they're making legitimate requests. If such a mechanism is in place, the quality of an anti-fraud system will be dramatically improved, as it allows for increasing system sensitivity and enabling pro-active defense, i.e., asking users to pass the tests in advance.

    In the case of services for end users, the main method of acquiring the second factor is redirecting to a captcha page. In the case of APIs it might be problematic, especially if you initially neglected the “Stipulate Restrictions” rule we've given in the “Describing Final Interfaces” chapter. In many cases, you will have to impose this responsibility on partners (i.e., it will be partners who show captchas and identify users based on the signals received from the API endpoints). This will, of course, significantly impair the convenience of working with the API.

    -

    NB. Instead of captcha, there might be other actions introducing additional authentication factors. It might be the phone number confirmation or the second step of the 3D-Secure protocol. The important part is that requesting an additional authentication step must be stipulated in the program interface, as it can't be added later in a backwards-compatible manner.

    +

    NB. Instead of captcha, there might be other actions introducing additional authentication factors. It might be the phone number confirmation or the second step of the 3D-Secure protocol. The important part is that requesting an additional authentication step must be stipulated in the program interface, as it can't be added later in a backward-compatible manner.

    Other popular mechanics of identifying robots include offering a bait (“honeypot”) or employing the execution environment checks (starting from rather trivial ones like executing JavaScript on the webpage and ending with sophisticated techniques of checking application integrity checksums).

    3. Restricting Access

    The illusion of having a broad choice of technical means of identifying fraud users should not deceive you as you will soon discover the lack of effective methods of restricting those users. Banning them by cookie / Referer / User-Agent makes little to no impact as this data is supplied by clients, and might be easily forged. In the end, you have four mechanisms for suppressing illegal activities:

    @@ -5288,9 +5287,9 @@ X-ApiName-Partner-Id: <partner_id>

    In this aspect, integrating with large companies that have a dedicated software engineering department differs dramatically from providing a solution to individual amateur programmers: on one hand, the former are much more likely to find undocumented features and unfixed bugs in your code; on the other hand, because of the internal bureaucracy, fixing the related issues might easily take months, save not years. The common recommendation there is to maintain old minor API versions for a period of time long enough for the most dilatory partner to switch no the newest version.

    Supporting Platforms

    Another aspect crucial to interacting with large integrators is supporting a zoo of platforms (browsers, programming languages, protocols, operating systems) and their versions. As usual, big companies have their own policies on which platforms they support, and these policies might sometimes contradict common sense. (Let's say, it's rather a time to abandon TLS 1.2, but many integrators continue working through this protocol, or even the earlier ones.)

    -

    Formally speaking, ceasing support of a platform is a backwards-incompatible change, and might lead to breaking some integration for some end users. So it's highly important to have clearly formulated policies regarding which platforms are supported based on which criteria. In the case of mass public APIs, that's usually simple (like, API vendor promises to support platforms that have more than N% penetration, or, even easier, just last M versions of a platform); in the case of commercial APIs, it's always a bargain based on the estimations, how much will non-supporting a specific platform would cost to a company. And of course, the outcome of the bargain must be stated in the contracts — what exactly you're promising to support during which period of time.

    +

    Formally speaking, ceasing support of a platform is a backward-incompatible change, and might lead to breaking some integration for some end users. So it's highly important to have clearly formulated policies regarding which platforms are supported based on which criteria. In the case of mass public APIs, that's usually simple (like, API vendor promises to support platforms that have more than N% penetration, or, even easier, just last M versions of a platform); in the case of commercial APIs, it's always a bargain based on the estimations, how much will non-supporting a specific platform would cost to a company. And of course, the outcome of the bargain must be stated in the contracts — what exactly you're promising to support during which period of time.

    Moving Forward

    -

    Finally, apart from those specific issues, your customers must be caring about more general questions: could they trust you? Could they rely on your API evolving, absorbing modern trends, or will they eventually find the integration with your API on the scrapyard of history? Let's be honest: given all the uncertainties of the API product vision, we are very much interested in the answers as well. Even the Roman viaduct, though remaining backwards-compatible for two thousand years, has been a very archaic and non-reliable way of solving customers' problems for quite a long time.

    +

    Finally, apart from those specific issues, your customers must be caring about more general questions: could they trust you? Could they rely on your API evolving, absorbing modern trends, or will they eventually find the integration with your API on the scrapyard of history? Let's be honest: given all the uncertainties of the API product vision, we are very much interested in the answers as well. Even the Roman viaduct, though remaining backward-compatible for two thousand years, has been a very archaic and non-reliable way of solving customers' problems for quite a long time.

    You might work with these customer expectations by publishing roadmaps. It's quite common that many companies avoid publicly announcing their concrete plans (for a reason, of course). Nevertheless, in the case of APIs, we strongly recommend providing the roadmaps, even if they are tentative and lack precise dates — especially if we talk about deprecating some functionality. Announcing these promises (given the company keeps them, of course) is a very important competitive advantage to every kind of consumer.

    With this, we would like to conclude this book. We hope that the principles and the concepts we have outlined will help you in creating APIs that fit all the developers, businesses, and end users' needs, and in expanding them (while maintaining the backward compatibility) for the next two thousand years or so.

NB. Sometimes to defend the concept of a single accessible API version, the following argument is put forward: preserving the SDK or API application server code is not enough to maintain strict backward compatibility as it might rely on some unversioned services (for example, data in the DB shared between all API versions). However, we consider this an additional reason to isolate such dependencies (see “The Serenity Notepad” chapter) as it means that changes to these subsystems might result in the API becoming inoperable.