You've already forked The-API-Book
mirror of
https://github.com/twirl/The-API-Book.git
synced 2025-09-16 08:46:18 +02:00
code listing chapter deleted
This commit is contained in:
Sergey Konstantinov
@@ -1,190 +0,0 @@
|
||||
### Annex to Section I. Generic API Example
|
||||
|
||||
Let's summarize the current state of our API study.
|
||||
|
||||
##### Offer Search
|
||||
|
||||
```json
|
||||
POST /v1/offers/search
|
||||
{
|
||||
// optional
|
||||
"recipes": ["lungo", "americano"],
|
||||
"position": <geographical coordinates>,
|
||||
"sort_by": [ { "field": "distance" } ],
|
||||
"limit": 10
|
||||
}
|
||||
→
|
||||
{
|
||||
"results": [{
|
||||
// Place data
|
||||
"place": { "name", "location" },
|
||||
// Coffee machine properties
|
||||
"coffee-machine": { "id", "brand", "type" },
|
||||
// Route data
|
||||
"route": {
|
||||
"distance", "duration", "location_tip"
|
||||
},
|
||||
"offers": [{
|
||||
// Recipe data
|
||||
"recipe":
|
||||
{ "id", "name", "description" },
|
||||
// Recipe specific options
|
||||
"options": { "volume" },
|
||||
// Offer metadata
|
||||
"offer": { "id", "valid_until" },
|
||||
// Pricing
|
||||
"pricing": {
|
||||
"currency_code", "price",
|
||||
"localized_price"
|
||||
},
|
||||
"estimated_waiting_time"
|
||||
}, …]
|
||||
}, …],
|
||||
"cursor"
|
||||
}
|
||||
```
|
||||
|
||||
##### Working with Recipes
|
||||
|
||||
```json
|
||||
// Returns a list of recipes
|
||||
// Cursor parameter is optional
|
||||
GET /v1/recipes?cursor=<cursor>
|
||||
→
|
||||
{ "recipes", "cursor" }
|
||||
```
|
||||
|
||||
```json
|
||||
// Returns the recipe by its id
|
||||
GET /v1/recipes/{id}
|
||||
→
|
||||
{
|
||||
"recipe_id",
|
||||
"name",
|
||||
"description"
|
||||
}
|
||||
```
|
||||
|
||||
##### Working with Orders
|
||||
|
||||
```json
|
||||
// Creates an order
|
||||
POST /v1/orders
|
||||
X-Idempotency-Token: <token>
|
||||
{
|
||||
"coffee_machine_id",
|
||||
"currency_code",
|
||||
"price",
|
||||
"recipe": "lungo",
|
||||
// Optional
|
||||
"offer_id",
|
||||
// Optional
|
||||
"volume": "800ml"
|
||||
}
|
||||
→
|
||||
{ "order_id" }
|
||||
```
|
||||
|
||||
```json
|
||||
// Returns the order by its id
|
||||
GET /v1/orders/{id}
|
||||
→
|
||||
{ "order_id", "status" }
|
||||
```
|
||||
|
||||
```json
|
||||
// Cancels the order
|
||||
POST /v1/orders/{id}/cancel
|
||||
```
|
||||
|
||||
##### Working with Programs
|
||||
|
||||
```json
|
||||
// Returns an identifier of the program
|
||||
// corresponding to specific recipe
|
||||
// on specific coffee-machine
|
||||
POST /v1/program-matcher
|
||||
{ "recipe", "coffee-machine" }
|
||||
→
|
||||
{ "program_id" }
|
||||
```
|
||||
|
||||
```json
|
||||
// Return program description
|
||||
// by its id
|
||||
GET /v1/programs/{id}
|
||||
→
|
||||
{
|
||||
"program_id",
|
||||
"api_type",
|
||||
"commands": [
|
||||
{
|
||||
"sequence_id",
|
||||
"type": "set_cup",
|
||||
"parameters"
|
||||
},
|
||||
…
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
##### Running Programs
|
||||
|
||||
```json
|
||||
// Runs the specified program
|
||||
// on the specified coffee-machine
|
||||
// with specific parameters
|
||||
POST /v1/programs/{id}/run
|
||||
X-Idempotency-Token: <token>
|
||||
{
|
||||
"order_id",
|
||||
"coffee_machine_id",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "volume",
|
||||
"value": "800ml"
|
||||
}
|
||||
]
|
||||
}
|
||||
→
|
||||
{ "program_run_id" }
|
||||
```
|
||||
|
||||
```json
|
||||
// Stops program running
|
||||
POST /v1/runs/{id}/cancel
|
||||
```
|
||||
|
||||
##### Managing Runtimes
|
||||
|
||||
```json
|
||||
// Creates a new runtime
|
||||
POST /v1/runtimes
|
||||
X-Idempotency-Token: <token>
|
||||
{
|
||||
"coffee_machine_id",
|
||||
"program_id",
|
||||
"parameters"
|
||||
}
|
||||
→
|
||||
{ "runtime_id", "state" }
|
||||
```
|
||||
|
||||
```json
|
||||
// Returns the state
|
||||
// of the specified runtime
|
||||
GET /v1/runtimes/{runtime_id}/state
|
||||
{
|
||||
"status": "ready_waiting",
|
||||
// Command being currently executed
|
||||
// (optional)
|
||||
"command_sequence_id",
|
||||
"resolution": "success",
|
||||
"variables"
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
// Terminates the runtime
|
||||
POST /v1/runtimes/{id}/terminate
|
||||
```
|
||||
@@ -1,192 +0,0 @@
|
||||
### Приложение к разделу I. Модельный API
|
||||
|
||||
Суммируем текущее состояние нашего учебного API.
|
||||
|
||||
##### Поиск предложений
|
||||
|
||||
```json
|
||||
POST /v1/offers/search
|
||||
{
|
||||
// опционально
|
||||
"recipes": ["lungo", "americano"],
|
||||
"position": <географические координаты>,
|
||||
"sort_by": [ { "field": "distance" } ],
|
||||
"limit": 10
|
||||
}
|
||||
→
|
||||
{
|
||||
"results": [{
|
||||
// Данные о заведении
|
||||
"place": { "name", "location" },
|
||||
// Данные о кофемашине
|
||||
"coffee_machine": { "id", "brand", "type" },
|
||||
// Как добраться
|
||||
"route":
|
||||
{ "distance", "duration", "location_tip" },
|
||||
// Предложения напитков
|
||||
"offers": [{
|
||||
// Рецепт
|
||||
"recipe": { "id", "name", "description" },
|
||||
// Данные относительно того,
|
||||
// как рецепт готовят
|
||||
// на конкретной кофемашине
|
||||
"options": { "volume" },
|
||||
// Метаданные предложения
|
||||
"offer": { "id", "valid_until" },
|
||||
// Цена
|
||||
"pricing": {
|
||||
"currency_code",
|
||||
"price",
|
||||
"localized_price"
|
||||
},
|
||||
"estimated_waiting_time"
|
||||
}, …]
|
||||
}, …]
|
||||
"cursor"
|
||||
}
|
||||
```
|
||||
|
||||
##### Работа с рецептами
|
||||
|
||||
```json
|
||||
// Возвращает список рецептов
|
||||
// Параметр cursor необязателен
|
||||
GET /v1/recipes?cursor=<курсор>
|
||||
→
|
||||
{ "recipes", "cursor" }
|
||||
```
|
||||
|
||||
```json
|
||||
// Возвращает конкретный рецепт
|
||||
// по его идентификатору
|
||||
GET /v1/recipes/{id}
|
||||
→
|
||||
{
|
||||
"recipe_id",
|
||||
"name",
|
||||
"description"
|
||||
}
|
||||
```
|
||||
|
||||
##### Работа с заказами
|
||||
|
||||
```json
|
||||
// Размещает заказ
|
||||
POST /v1/orders
|
||||
X-Idempotency-Token: <токен>
|
||||
{
|
||||
"coffee_machine_id",
|
||||
"currency_code",
|
||||
"price",
|
||||
"recipe": "lungo",
|
||||
// Опционально
|
||||
"offer_id",
|
||||
// Опционально
|
||||
"volume": "800ml"
|
||||
}
|
||||
→
|
||||
{ "order_id" }
|
||||
```
|
||||
|
||||
```json
|
||||
// Возвращает состояние заказа
|
||||
GET /v1/orders/{id}
|
||||
→
|
||||
{ "order_id", "status" }
|
||||
```
|
||||
|
||||
```json
|
||||
// Отменяет заказ
|
||||
POST /v1/orders/{id}/cancel
|
||||
```
|
||||
##### Работа с программами
|
||||
|
||||
```json
|
||||
// Возвращает идентификатор программы,
|
||||
// соответствующей указанному рецепту
|
||||
// на указанной кофемашине
|
||||
POST /v1/program-matcher
|
||||
{ "recipe", "coffee_machine" }
|
||||
→
|
||||
{ "program_id" }
|
||||
```
|
||||
|
||||
```json
|
||||
// Возвращает описание
|
||||
// программы по её идентификатору
|
||||
GET /v1/programs/{id}
|
||||
→
|
||||
{
|
||||
"program_id",
|
||||
"api_type",
|
||||
"commands": [
|
||||
{
|
||||
"sequence_id",
|
||||
"type": "set_cup",
|
||||
"parameters"
|
||||
},
|
||||
…
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
##### Исполнение программ
|
||||
|
||||
```json
|
||||
// Запускает исполнение программы
|
||||
// с указанным идентификатором
|
||||
// на указанной машине
|
||||
// с указанными параметрами
|
||||
POST /v1/programs/{id}/run
|
||||
X-Idempotency-Token: <токен>
|
||||
{
|
||||
"order_id",
|
||||
"coffee_machine_id",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "volume",
|
||||
"value": "800ml"
|
||||
}
|
||||
]
|
||||
}
|
||||
→
|
||||
{ "program_run_id" }
|
||||
```
|
||||
|
||||
```json
|
||||
// Останавливает исполнение программы
|
||||
POST /v1/runs/{id}/cancel
|
||||
```
|
||||
|
||||
##### Управление рантаймами
|
||||
|
||||
```json
|
||||
// Создаёт новый рантайм
|
||||
POST /v1/runtimes
|
||||
{
|
||||
"coffee_machine_id",
|
||||
"program_id",
|
||||
"parameters"
|
||||
}
|
||||
→
|
||||
{ "runtime_id", "state" }
|
||||
```
|
||||
|
||||
```json
|
||||
// Возвращает текущее состояние рантайма
|
||||
// по его id
|
||||
GET /v1/runtimes/{runtime_id}/state
|
||||
{
|
||||
"status": "ready_waiting",
|
||||
// Текущая исполняемая команда
|
||||
// (необязательное)
|
||||
"command_sequence_id",
|
||||
"resolution": "success",
|
||||
"variables"
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
// Прекращает исполнение рантайма
|
||||
POST /v1/runtimes/{id}/terminate
|
||||
```
|
||||
Reference in New Issue
Block a user