diff --git a/docs/API.en.epub b/docs/API.en.epub index c28c169..0ed1799 100644 Binary files a/docs/API.en.epub and b/docs/API.en.epub differ diff --git a/docs/API.en.html b/docs/API.en.html index 4972c39..11fb940 100644 --- a/docs/API.en.html +++ b/docs/API.en.html @@ -624,7 +624,7 @@ ul.references li p a.back-anchor {

What differs between a Roman aqueduct and a good API is that in the case of APIs, the contract is presumed to be programmable. To connect the two areas, writing some code is needed. The goal of this book is to help you design APIs that serve their purposes as solidly as a Roman aqueduct does.

An aqueduct also illustrates another problem with the API design: your customers are engineers themselves. You are not supplying water to end-users. Suppliers are plugging their pipes into your engineering structure, building their own structures upon it. On the one hand, you may provide access to water to many more people through them, not spending your time plugging each individual house into your network. On the other hand, you can't control the quality of suppliers' solutions, and you are to blame every time there is a water problem caused by their incompetence.

That's why designing an API implies a larger area of responsibility. An API is a multiplier to both your opportunities and your mistakes.

Chapter 3. Overview of Existing API Development Solutions 

-

In the first three sections of this book, we aim to discuss API design in general, not bound to any specific technology. The concepts we describe are equally applicable to web services and, let's say, operating systems (OS) APIs.

+

In the first three sections of this book, we aim to discuss API design in general, not bound to any specific technology. The concepts we describe are equally applicable to, let's say, web services and operating system (OS) APIs.

Still, two main scenarios dominate the stage when we talk about API development:

In the first case, we almost universally talk about APIs working atop the HTTP protocol. Today, the only notable examples of non-HTTP-based client-server interaction protocols are WebSocket (though it might, and frequently does, work in conjunction with HTTP) and highly specialized APIs like media streaming and broadcasting formats.

HTTP API

-

Though the technology looks homogenous because of using the same application-level protocol, in reality, there is significant diversity regarding different approaches to realizing HTTP-based APIs.

+

Although the technology looks homogeneous because of using the same application-level protocol, in reality, there is significant diversity regarding different approaches to realizing HTTP-based APIs.

First, implementations differ in terms of utilizing HTTP capabilities:

-
  • the API must be readable; +
  • the API must be readable -

    The term “client” here stands for an application being executed on a user's device, either a native or a web one. The terms “agent” and “user agent” are synonymous to “client.”

    +

    The term “client” here stands for an application being executed on a user's device, either a native or a web one. The terms “agent” and “user agent” are synonymous with “client.”

    Some request and response parts might be omitted if they are irrelevant to the topic being discussed.

    Simplified notation might be used to avoid redundancies, like POST /some-resource {…, "some_parameter", …} → { "operation_id" }; request and response bodies might also be omitted.

    -

    We will be using sentences like “POST /v1/bucket/{id}/some-resource method” (or simply “bucket/some-resource method,” “some-resource” method — if there are no other some-resources in the chapter, so there is no ambiguity) to refer to such endpoint definitions.

    -

    Apart from HTTP API notation, we will employ C-style pseudocode, or, to be more precise, JavaScript-like or Python-like one, since types are omitted. We assume such imperative structures are readable enough to skip detailed grammar explanations.

    Section I. The API Design

    Chapter 9. The API Contexts Pyramid 

    +

    We will use sentences like “POST /v1/bucket/{id}/some-resource method” (or simply “bucket/some-resource method,” “some-resource” method — if there are no other some-resources in the chapter, so there is no ambiguity) to refer to such endpoint definitions.

    +

    Apart from HTTP API notation, we will employ C-style pseudocode, or, to be more precise, JavaScript-like or Python-like one since types are omitted. We assume such imperative structures are readable enough to skip detailed grammar explanations.

    Section I. The API Design

    Chapter 9. The API Contexts Pyramid 

    The approach we use to design APIs comprises four steps: