Files
apostol-dm/doc/REST-API-ru.md
Преподобный Ален 0cdf38795b Committing updates.
2022-07-04 23:02:35 +03:00

590 lines
20 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# API "Модуля сделок" системы учёта Bitcoin платежей.
## Общая информация
* Базовая конечная точка (endpoint): [localhost:4999](http://localhost:4999)
* Все конечные точки возвращают `JSON-объект`
* Все поля, относящиеся ко времени и меткам времени, указаны в **миллисекундах**.
## HTTP коды возврата
* HTTP `4XX` коды возврата применимы для некорректных запросов - проблема на стороне клиента.
* HTTP `5XX` коды возврата используются для внутренних ошибок - проблема на стороне сервера. Важно **НЕ** рассматривать это как операцию сбоя. Статус выполнения **НЕИЗВЕСТЕН** и может быть успешным.
## Коды ошибок
* Любая конечная точка может вернуть ошибку.
**Пример ответа:**
```json
{
"error": {
"code": 404,
"message": "Not Found"
}
}
```
## Общая информация о конечных точках
* Для `GET` конечных точек параметры должны быть отправлены в виде `строки запроса (query string)` .
* Для `POST` конечных точек, некоторые параметры могут быть отправлены в виде `строки запроса (query string)`, а некоторые в виде `тела запроса (request body)`:
* При отправке параметров в виде `тела запроса` допустимы следующие типы контента:
* `application/x-www-form-urlencoded` для `query string`;
* `multipart/form-data` для `HTML-форм`;
* `application/json` для `JSON`;
* `text/plain` для `YAML` или `текста в произвольном формате`.
* Параметры могут быть отправлены в любом порядке.
## Доступ к API
Доступ к API возможен только при наличии _**маркера доступа**_ или **_цифровой подписи_** методом HMAC-SHA256.
[Подробнее](https://github.com/ufocomp/db-platform/wiki/%D0%94%D0%BE%D1%81%D1%82%D1%83%D0%BF-%D0%BA-API).
## Общие конечные точки
### Тест подключения
```http
GET /api/v1/ping HTTP/1.1
```
Проверить подключение к REST API.
**Параметры:**
НЕТ
**Пример ответа:**
```json
{}
```
### Проверить время сервера
```http
GET /api/v1/time HTTP/1.1
```
Проверить подключение к REST API и получить текущее время сервера.
**Параметры:**
НЕТ
**Пример ответа:**
```json
{
"serverTime": 1583495795455
}
```
## Конечные точки
Конечные точки разделены на две категории: `Пользователи (account)` и `Сделки (deal)`.
Обработка запросов выполняется на стороне `Дополнительного сервера (ДС)`.
Поэтому `Модуль сделок` формирует **транспортный пакет** в виде `JSON-объекта` и отправляет его на `ДС`.
###### ВАЖНО: Сетевой адрес `Дополнительного сервера (ДС)` можно указать в параметрах запроса в виде `строки запроса`. По умолчанию: `localhost`
### Формат транспортного пакета:
**Запрос:**
```json
{
"id": "<string>",
"address": "<string>",
"action": "<string>",
"payload": "<base64>"
}
```
**Ответ:**
```json
{
"id": "<string>",
"address": "<string>",
"action": "<string>",
"result": {
"success": "<boolean>",
"message": "<string>"
},
"payload": "<base64>"
}
```
**Описание:**
Ключ | Тип | Значение | Описание
------------ | ------------ | ------------ | ------------
id | STRING | | Уникальный идентификатор запроса
address | STRING | | Bitcoin адрес пользователя (учётной записи) `ДС`. По умолчанию: Адрес модуля
action | STRING | `help`, `status`, `new`, `add`, `update`, `token`, `delete` | Действие
token | JSON | | Маркер доступа
result | JSON | | Результат выполнения запроса
success | BOOLEAN | true, false | Успешно: Да/Нет
message | STRING | | Сообщение (информация об ошибке)
payload | BASE64 | | Полезная нагрузка (строка в формате Base64)
`Полезная нагрузка` может содержать данные в виде:
* `HTML-документа`;
* `JSON-объекта`;
* `Текста в произвольном формате`.
### Общие параметры
#### Для последующих конечных точек можно указать **параметры** в виде `строки запроса (query string)`:
Имя | Тип | Значение | Описание
------------ | ------------ | ------------ | ------------
payload | STRING | text, html, json, xml | Получить ответ в виде содержимого поля `payload` с указанием формата
server | STRING | localhost | IP-адрес или Host имя сервера (ДС). По умолчанию: localhost
pgp | BOOLEAN | false, off | Отключить PGP подпись модуля сделок
address | STRING | | Bitcoin адрес пользователя (учётной записи) `ДС`. По умолчанию: Адрес модуля
## Параметры пользователя
### Параметры в виде `тела запроса (request body)`:
Наименование | Тип | Действие | Описание
------------ | ------------ | ------------ | ------------
address | STRING | * | Bitcoin адрес
bitmessage | STRING or JSON array | `new` | Bitmessage адрес или массив адресов
email | STRING | `new` | Почтовый адрес
password | STRING | `new` | Пароль
key | STRING | `new`, `add` | Bitcoin ключ (публичный)
pgp | STRING | `new`, `add` | PGP ключ (публичный)
url | STRING | `new`, `update` | Список URL
date | STRING | `update`, `delete` | Дата в формате: YYYY-MM-DD
code | STRING | `token` | Произвольная строка которую нужно подписать.
sign | STRING | `update`, `token`, `delete` | Bitcoin подпись
flags | STRING | `delete` | Флаги
## Параметры сделки
### Параметры в виде `тела запроса (request body)`:
#### Для типов контента `application/x-www-form-urlencoded` и `multipart/form-data`:
Наименование | Тип | Действие | Описание
------------ | ------------ | ------------ | ------------
type | STRING | * | Тип
at | URL | * | URL сайта
date | DATETIME | * | Дата сделки
seller_address | STRING | * | Продавец: Bitcoin адрес
seller_rating | STRING | Pay, Complete | Продавец: Рейтинг
customer_address | STRING | * | Покупатель: Bitcoin адрес
customer_rating | STRING | Pay, Complete | Покупатель: Рейтинг
payment_address | STRING | Pay, Complete | Оплата: Bitcoin адрес
payment_until | DATETIME | Pay, Complete | Оплата: Срок оплаты
payment_sum | DOUBLE | * | Оплата: Сумма
feedback_leave_before | DATETIME | Pay, Complete | Обратная связь: Срок до...
feedback_status | STRING | Complete | Обратная связь: Статус
feedback_comments | STRING | Complete | Обратная связь: Комментарий
#### Для типа контента `application/json`:
```json
{
"order": "<string>",
"type": "<string>",
"at": "<url>",
"date": "<datetime>",
"seller": {
"address": "<string>",
"rating": "<string>"
},
"customer": {
"address": "<string>",
"rating": "<string>"
},
"payment": {
"address": "<string>",
"until": "<datetime>",
"sum": "<double>"
},
"feedback": {
"leave-before": "<datetime>",
"status": "<string>",
"comments": "<string>"
}
}
```
#### Для типа контента `text/plain`:
```yaml
deal:
order: <string>
type: <string>
at: <url>
date: <datetime>
seller:
address: <string>
rating: <string>
customer:
address: <string>
rating: <string>
payment:
sum: <double>
address: <string>
until: <datetime>
feedback:
leave-before: <datetime>
status: <string>
comments: <string>
```
### Новая сделка (ордер)
Ордер создается без указания адреса платежа (поле `payment`). Адрес платежа связан с исходными данными ордера. Зная исходные данные ордера можно вычислить адрес платежа.
Адрес платежа создается модулем сделок.
**Пример:**
Минимально необходимый набор данных для создания ордера (в формате JSON) предоставлен ниже:
Запрос:
```http
POST /api/v1/deal HTTP/1.1
```
Тело запроса
```json
{
"order": "create",
"type": "Prepaid",
"at": "http://placard.zr-code.com",
"date": "2022-04-11 11:14:46 UTC",
"seller": {
"address": "n2f3cbeUUFhbz6mFLpDUzMnrt72sPu7WQK"
},
"customer": {
"address": "2N3oefVeg6stiTb5Kh3ozCSkaqmx91FDbsm"
},
"payment": {
"until": "2022-04-12 11:14:46 UTC",
"sum": 0.00001
}
}
```
Ответ:
```json
{
"id": "AEEAB-PEE95-O6F30-S68A8-TC55A-O3B7D-L98370",
"action": "Created",
"result": {
"success": true,
"message": "New deal submitted"
},
"payload": "LS0tLS1CRUdJTiBQR1AgU0lHTkVEIE1FU1NBR0UtLS0tLQpIYXNoOiBTSEE1MTIKCmRlYWw6CiAgb3JkZXI6IENyZWF0ZWQKICB0eXBlOiBQcmVwYWlkCiAgYXQ6IGh0dHA6Ly9wbGFjYXJkLnpyLWNvZGUuY29tCiAgZGF0ZTogMjAyMi0wNC0xMSAxMToxNDo0NiBVVEMKICBzZWxsZXI6CiAgICBhZGRyZXNzOiBuMmYzY2JlVVVGaGJ6Nm1GTHBEVXpNbnJ0NzJzUHU3V1FLCiAgICByYXRpbmc6IDAsIDAlCiAgY3VzdG9tZXI6CiAgICBhZGRyZXNzOiAyTjNvZWZWZWc2c3RpVGI1S2gzb3pDU2thcW14OTFGRGJzbQogICAgcmF0aW5nOiAwLCAwJQogIHBheW1lbnQ6CiAgICB1bnRpbDogMjAyMi0wNC0xMiAxMToxNDo0NiBVVEMKICAgIGFkZHJlc3M6IDJONmFidjNxaGdIUXh2bnRmRHptbWk0a0htMTRUYWRvQnB1CiAgICBzdW06IDAuMDAwMDEgdEJUQwogIGZlZWRiYWNrOgogICAgbGVhdmUtYmVmb3JlOiAyMDIyLTA0LTEyIDExOjE0OjQ2IFVUQwotLS0tLUJFR0lOIFBHUCBTSUdOQVRVUkUtLS0tLQpWZXJzaW9uOiBjYwoKd3B3RUFRRUtBQVlGQW1KVURid0FDZ2tRN0lqUjIwSkJpemVCckFRQWp0UlU5R3IySm1qdUhLTHhaejQrVWMzQwp2cUFzem1JcjhZRUdRUWZKS3o3SjJsd1U0ZkNOaVByZ29yQTdIdVRGa1Bqd0JrN0N0MHBOZlQwWmpxYTVYWXk5Cml1d01hRkVsM1dmVUQ0MlQxQVFWUDhCbUp6RmtxUXdVSE81dWtDS1RpaTViK3VHVVIvZzJETStFOXVBb3ZYWEYKZ3M5NldWVlJzNGg5YWdCektPTT0KPW4razcKLS0tLS1FTkQgUEdQIFNJR05BVFVSRS0tLS0t"
}
```
Расшифровка `payload`:
```yaml
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512
deal:
order: Created
type: Prepaid
at: http://placard.zr-code.com
date: 2022-04-11 11:14:46 UTC
seller:
address: n2f3cbeUUFhbz6mFLpDUzMnrt72sPu7WQK
rating: 0, 0%
customer:
address: 2N3oefVeg6stiTb5Kh3ozCSkaqmx91FDbsm
rating: 0, 0%
payment:
until: 2022-04-12 11:14:46 UTC
address: 2N6abv3qhgHQxvntfDzmmi4kHm14TadoBpu
sum: 0.00001 tBTC
feedback:
leave-before: 2022-04-12 11:14:46 UTC
-----BEGIN PGP SIGNATURE-----
Version: cc
wpwEAQEKAAYFAmJUDbwACgkQ7IjR20JBizeBrAQAjtRU9Gr2JmjuHKLxZz4+Uc3C
vqAszmIr8YEGQQfJKz7J2lwU4fCNiPrgorA7HuTFkPjwBk7Ct0pNfT0Zjqa5XYy9
iuwMaFEl3WfUD42T1AQVP8BmJzFkqQwUHO5ukCKTii5b+uGUR/g2DM+E9uAovXXF
gs96WVVRs4h9agBzKOM=
=n+k7
-----END PGP SIGNATURE-----
```
## Пользователь
### Помощь
```http
GET /api/v1/help HTTP/1.1
```
```http
POST /api/v1/help HTTP/1.1
```
Получить справочную информацию по командам регистрации и обновления данных учётной записи.
**Параметры:**
[Строка запроса](#общие-параметры)
**Пример:**
Запрос:
```http
GET /api/v1/help?payload=html HTTP/1.1
```
Ответ (содержимое `payload`):
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="author" content="Bitcoin Payment Service">
</head>
<body>
<pre>
Bitcoin Payment Service.
Usage: Send a message in accordance with the format.
Available actions:
<b>help</b> : send this help
<b>status</b> : show account data
<b>new</b> : create account
<b>add</b> : adding data to a account (adding missing data)
<b>update</b> : updating account data
<b>token</b> : get access token
<b>delete</b> : delete account
The system has an AI and can determine the action itself.
But you can help the AI and indicate the action explicitly in the message subject.
Subject: [help|status|new|add|update|delete] | any text
Body:
Action : Message format
<b>help</b> : &lt;ignored&gt;
<b>status</b> : &lt;ignored&gt;
<b>new</b> : &lt;bitcoin&gt;&lt;LF&gt;
[&lt;key&gt;&lt;LF&gt;] |
[&lt;PGP&gt;&lt;LF&gt;] |
[{account:|trusted:}&lt;LF&gt;]
[&lt;url&gt;&lt;LF&gt;]
<b>add</b> : [&lt;key&gt;&lt;LF&gt;] |
[&lt;PGP&gt;&lt;LF&gt;]
<b>update</b> : &lt;yyyy-mm-dd&gt;&lt;LF&gt;
[&lt;PGP&gt;&lt;LF&gt;] |
[{account:|trusted:}&lt;LF&gt;]
[&lt;url&gt;&lt;LF&gt;] |
&lt;signature&gt;
<b>token</b> : &lt;code&gt;&lt;LF&gt;
&lt;signature&gt;
<b>delete</b> : &lt;yyyy-mm-dd&gt;&lt;LF&gt;
-account&lt;LF&gt;
&lt;signature&gt;
Arguments:
account : account URL list (default if not set "trusted")
trusted : trusted URL list
-account : delete account
Templates:
&lt;ignored&gt; : any text will be ignored
&lt;LF&gt; : line feed; format: 0x0a
&lt;string&gt; : single line text
&lt;bitcoin&gt; : bitcoin address; format: [bitcoin:]&lt;string&gt;
&lt;key&gt; : bitcoin public key
&lt;PGP&gt; : PGP public key
&lt;yyyy-mm-dd&gt; : current date
&lt;code&gt; : unique string
[+|-]&lt;url&gt; : add(+) or delete(-) URL; format: http[s]://&lt;string&gt;
&lt;signature&gt; : bitcoin signature for message text (use private key)</pre>
</body>
</html>
```
###### Этот HTML-документ содержит инструкцию к составлению данных в виде `текста в произвольном формате`.
### Статус
```http
GET /api/v1/account/status HTTP/1.1
```
```http
POST /api/v1/account/status HTTP/1.1
```
Получить статус учётной записи пользователя.
**Параметры:**
[Строка запроса](#общие-параметры)
**Пример:**
Запрос:
```http
GET /api/v1/account/status?address=null HTTP/1.1
```
Ответ:
```json
{
"id": "A4406-PDF10-OE2BC-SF8AA-T918F-OC9BC-L9EB00",
"action": "Status",
"result": {
"success": false,
"message": "Invalid Bitcoin address: null"
},
"payload": "PCFET0NUWVBFIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KPGhlYWQ+CiAgICA8bWV0YSBjaGFyc2V0PSJVVEYtOCI+CiAgICA8bWV0YSBuYW1lPSJhdXRob3IiIGNvbnRlbnQ9IkJpdGNvaW4gUGF5bWVudCBTZXJ2aWNlIj4KPC9oZWFkPgo8Ym9keT4KPHByZT5IZWxsbyEKClNvcnJ5LCBzb21ldGhpbmcgd2VudCB3cm9uZyBhbmQgbGVkIHRvIGFuIGVycm9yOgoKPGZvbnQgY29sb3I9IiNDMDM5MkIiPjxiPkludmFsaWQgQml0Y29pbiBhZGRyZXNzOiBudWxsPC9iPjwvZm9udD4KCi0tLS0tClRoYW5rIHlvdSwKUGF5bWVudHMubmV0PC9wcmU+CjwvYm9keT4KPC9odG1sPgo="
}
```
### Новый
```http
POST /api/v1/account/new HTTP/1.1
```
Зарегистрировать нового пользователя.
**Параметры:**
[Строка запроса](#общие-параметры),
[Тело запроса](#параметры-пользователя)
### Добавить
```http
POST /api/v1/account/add HTTP/1.1
```
Добавить данные в учётную запись пользователя.
**Параметры:**
[Строка запроса](#общие-параметры),
[Тело запроса](#параметры-пользователя)
### Обновить
```http
POST /api/v1/account/update HTTP/1.1
```
Обновить данные в учётной записи пользователя.
**Параметры:**
[Строка запроса](#общие-параметры),
[Тело запроса](#параметры-пользователя)
### Удалить
```http
POST /api/v1/account/delete HTTP/1.1
```
Удалить учётную запись пользователя.
**Параметры:**
[Строка запроса](#общие-параметры),
[Тело запроса](#параметры-пользователя)
## Сделка
### Создать
```http
POST /api/v1/deal/create HTTP/1.1
```
Создать сделку.
**Параметры:**
[Строка запроса](#общие-параметры),
[Тело запроса](#параметры-сделки)
### Оплатить
```http
POST /api/v1/deal/pay HTTP/1.1
```
Оплатить сделку.
**Параметры:**
[Строка запроса](#общие-параметры),
[Тело запроса](#параметры-сделки)
### Завершить
```http
POST /api/v1/deal/complete HTTP/1.1
```
Завершить сделку.
**Параметры:**
[Строка запроса](#общие-параметры),
[Тело запроса](#параметры-сделки)
## Примеры:
* **HTTP Request:**
```http
POST /api/v1/account/new HTTP/1.1
Host: localhost:4999
Content-Type: application/x-www-form-urlencoded
address=mynFyJJkRhsbB6y1Q5kTgDGckVz2m9NKH8&key=02ef68c191984433c8a730b8fa48a47ec016a0727e6d26cc0982c8900b39354f61
```
* **curl command:**
```curl
curl "http://localhost:4999/api/v1/account/new?payload=html" \
-X POST \
-d "address=mynFyJJkRhsbB6y1Q5kTgDGckVz2m9NKH8&key=02ef68c191984433c8a730b8fa48a47ec016a0727e6d26cc0982c8900b39354f61" \
-H "Content-Type: application/x-www-form-urlencoded"
```
* **HTTP Request:**
```http
POST /api/v1/account/new HTTP/1.1
Host: localhost:4999
Content-Type: application/json
```
* **HTTP Request:**
```http
POST /api/v1/account/new?payload=html HTTP/1.1
Host: localhost:4999
Content-Type: text/plain
```
* **curl command:**
```curl
curl "http://localhost:4999/api/v1/account/new?payload=html" \
-X POST \
-d "mynFyJJkRhsbB6y1Q5kTgDGckVz2m9NKH8\n02ef68c191984433c8a730b8fa48a47ec016a0727e6d26cc0982c8900b39354f61" \
-H "Content-Type: text/plain"
```
* **JavaScript:**
```javascript
let headers = new Headers();
headers.append('Content-Type', 'multipart/form-data');
let body = new FormData();
body.append("address", "mynFyJJkRhsbB6y1Q5kTgDGckVz2m9NKH8");
body.append("key", "02ef68c191984433c8a730b8fa48a47ec016a0727e6d26cc0982c8900b39354f61");
const init = {
method: 'POST',
headers: headers,
body: body,
mode: "cors"
};
fetch('http://localhost:4999/api/v1/account/new', init)
.then((response) => {
return response.json();
})
.then((json) => {
console.log(json);
console.log(window.atob(json['payload']));
})
.catch((e) => {
console.log(e.message);
});
```