books/The-API-Book
1
0
Fork 0
mirror of https://github.com/twirl/The-API-Book.git synced 2025-05-31 22:09:37 +02:00
Code Issues Releases Activity

Fix en version

Browse Source
This commit is contained in:
taksedo 2024-08-20 16:43:14 +03:00 committed by GitHub
parent bdff710d73
commit e6fcc4e58a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 5 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
src/en/clean-copy/01-Introduction/08.md
View File

@ -10,7 +10,8 @@ Let's take a look at the following example:
```json
// Method description
POST /v1/buckets/{id}/some-resources/{resource_id}
POST /v1/buckets/{id}/some-resources↵
/{resource_id}
X-Idempotency-Token: <idempotency token>
{
…
@ -32,7 +33,7 @@ Cache-Control: no-cache
```
It should be read like this:
* A client performs a `POST` request to a `/v1/bucket/{id}/some-resource` resource, where `{id}` is to be replaced with some `bucket`'s identifier (`{something}` notation refers to the nearest term from the left unless explicitly specified otherwise).
* A client performs a `POST` request to a `/v1/buckets/{id}/some-resources` resource, where `{id}` is to be replaced with some `bucket`'s identifier (`{something}` notation refers to the nearest term from the left unless explicitly specified otherwise).
* A specific `X-Idempotency-Token` header is added to the request alongside standard headers (which we omit).
* Terms in angle brackets (`<idempotency token>`) describe the semantics of an entity value (field, header, parameter).
* A specific JSON, containing a `some_parameter` field and some other unspecified fields (indicated by ellipsis) is being sent as a request body payload.
@ -45,8 +46,8 @@ The term “client” here stands for an application being executed on a user's
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.
Simplified notation might be used to avoid redundancies, like `POST /some-resources` `{…, "some_parameter", …}` → `{ "operation_id" }`; request and response bodies might also be omitted.
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-resource`s in the chapter, so there is no ambiguity) to refer to such endpoint definitions.
We will use sentences like “`POST /v1/buckets/{id}/some-resources` method” (or simply “`buckets/some-resources` method,” “`some-resources`” method — if there are no other `some-resources`s 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. HTTP API-like samples intend to illustrate the *contract*, i.e., how we would design an API. Samples in pseudocode are intended to illustrate how developers might work with the API in their code, or how we would implement SDKs based on the contract.