books/The-API-Book
1
0
Fork 0
mirror of https://github.com/twirl/The-API-Book.git synced 2025-07-12 22:50:21 +02:00
Code Issues Releases Activity

Fix ru version

Browse Source
This commit is contained in:
taksedo
2024-08-20 16:47:13 +03:00
committed by GitHub
parent e6fcc4e58a
commit 1830f94258
1 changed files with 5 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
src/ru/clean-copy/01-Введение/08.md
View File

@ -10,7 +10,8 @@
```json
// Описание метода
POST /v1/buckets/{id}/some-resources/{resource_id}
POST /v1/buckets/{id}/some-resources↵
/{resource_id}
X-Idempotency-Token: <токен идемпотентности>
{
…
@ -31,7 +32,7 @@ Cache-Control: no-cache
```
Её следует читать так:
* клиент выполняет POST-запрос к ресурсу `/v1/bucket/{id}/some-resource`, где `{id}` заменяется на некоторый идентификатор `bucket`-а (при отсутствии уточнений подстановки вида `{something}` следует относить к ближайшему термину слева);
* клиент выполняет POST-запрос к ресурсу `/v1/buckets/{id}/some-resources`, где `{id}` заменяется на некоторый идентификатор `bucket`-а (при отсутствии уточнений подстановки вида `{something}` следует относить к ближайшему термину слева);
* запрос сопровождается (помимо стандартных заголовков, которые мы опускаем) дополнительным заголовком `X-Idempotency-Token`;
* фразы в угловых скобках (`<токен идемпотентности>`) описывают семантику значения сущности (поля, заголовка, параметра);
* в качестве тела запроса передаётся JSON, содержащий поле `some_parameter` со значением `value` и ещё какие-то поля, которые для краткости опущены (что показано многоточием);
@ -44,8 +45,8 @@ Cache-Control: no-cache
Ответ (частично или целиком) и тело запроса могут быть опущены, если в контексте обсуждаемого вопроса их содержание не имеет значения.
Возможна сокращённая запись вида: `POST /some-resource` `{…,"some_parameter",…}` → `{ "operation_id" }`; тело запроса и/или ответа может опускаться аналогично полной записи.
Возможна сокращённая запись вида: `POST /some-resources` `{…,"some_parameter",…}` → `{ "operation_id" }`; тело запроса и/или ответа может опускаться аналогично полной записи.
Чтобы сослаться на это описание будут использоваться выражения типа «метод `POST /v1/bucket/{id}/some-resource`» или, для простоты, «метод `some-resource`» или «метод `bucket/some-resource`» (если никаких других `some-resource` в контексте главы не упоминается и перепутать не с чем).
Чтобы сослаться на это описание будут использоваться выражения типа «метод `POST /v1/buckets/{id}/some-resources`» или, для простоты, «метод `some-resources`» или «метод `buckets/some-resources`» (если никаких других `some-resources` в контексте главы не упоминается и перепутать не с чем).
Помимо HTTP API-нотации мы будем активно использовать C-подобный псевдокод — точнее будет сказать, JavaScript или Python-подобный, поскольку нотации типов мы будем опускать. Мы предполагаем, что подобного рода императивные конструкции достаточно читабельны, и не будем здесь описывать грамматику подробно. Примеры в виде HTTP API-нотации призваны иллюстрировать дизайн *контрактов*, т.е. показывать, как мы разрабатываем API. Примеры в псевдокоде обычно отражают, какой код напишут разработчики для работы с API, или как бы мы сами написали SDK на основе такого контракта.