private/apostol-dm
1
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
f4f4d104cfbacf0b3461851c19647072bce3b27c
apostol-dm/doc/REST-API-ru.md
Преподобный Ален f4f4d104cf Committing updates.
2021-09-17 15:04:26 +03:00

17 KiB
Raw Blame History

API "Модуля сделок" системы учёта Bitcoin платежей.

Общая информация

  • Базовая конечная точка (endpoint): localhost:4999
  • Все конечные точки возвращают JSON-объект
  • Все поля, относящиеся ко времени и меткам времени, указаны в миллисекундах.

HTTP коды возврата

  • HTTP 4XX коды возврата применимы для некорректных запросов - проблема на стороне клиента.
  • HTTP 5XX коды возврата используются для внутренних ошибок - проблема на стороне сервера. Важно НЕ рассматривать это как операцию сбоя. Статус выполнения НЕИЗВЕСТЕН и может быть успешным.

Коды ошибок

  • Любая конечная точка может вернуть ошибку.

Пример ответа:

{
  "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.

Подробнее.

Общие конечные точки

Тест подключения

GET /api/v1/ping

Проверить подключение к REST API.

Параметры: НЕТ

Пример ответа:

{}

Проверить время сервера

GET /api/v1/time

Проверить подключение к REST API и получить текущее время сервера.

Параметры: НЕТ

Пример ответа:

{
  "serverTime": 1583495795455
}

Конечные точки

Конечные точки разделены на две категории: Пользователи (account) и Сделки (deal).

Обработка запросов выполняется на стороне Дополнительного сервера (ДС). Поэтому Модуль сделок формирует транспортный пакет в виде JSON-объекта и отправляет его на ДС.

ВАЖНО: Сетевой адрес Дополнительного сервера (ДС) можно указать в параметрах запроса в виде строки запроса. По умолчанию: localhost

Формат транспортного пакета:

Запрос:

{
  "id": "<string>",
  "address": "<string>",
  "action": "<string>",
  "payload": "<base64>"
}

Ответ:

{
  "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, delete Действие
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 New Bitmessage адрес
key STRING New, Add Bitcoin ключ (публичный)
pgp STRING New, Add PGP ключ (публичный)
url STRING New, Update Список URL
date STRING Update, Delete Дата в формате: YYYY-MM-DD
sign STRING Update, 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:

{
  "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:

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>

Пользователь

Помощь

GET /api/v1/help

POST /api/v1/help

Получить справочную информацию по командам регистрации и обновления данных учётной записи.

Параметры: Строка запроса

Пример:

Запрос:

GET /api/v1/help?payload=html

Ответ (содержимое payload):

<!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>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>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;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-документ содержит инструкцию к составлению данных в виде текста в произвольном формате.

Статус

GET /api/v1/account/status

POST /api/v1/account/status

Получить статус учётной записи пользователя.

Параметры: Строка запроса

Пример:

Запрос:

GET /api/v1/account/status?address=null

Ответ:

{
"id": "A4406-PDF10-OE2BC-SF8AA-T918F-OC9BC-L9EB00",
"action": "Status",
"result": {
  "success": false,
  "message": "Invalid Bitcoin address: null"
},
"payload": "PCFET0NUWVBFIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KPGhlYWQ+CiAgICA8bWV0YSBjaGFyc2V0PSJVVEYtOCI+CiAgICA8bWV0YSBuYW1lPSJhdXRob3IiIGNvbnRlbnQ9IkJpdGNvaW4gUGF5bWVudCBTZXJ2aWNlIj4KPC9oZWFkPgo8Ym9keT4KPHByZT5IZWxsbyEKClNvcnJ5LCBzb21ldGhpbmcgd2VudCB3cm9uZyBhbmQgbGVkIHRvIGFuIGVycm9yOgoKPGZvbnQgY29sb3I9IiNDMDM5MkIiPjxiPkludmFsaWQgQml0Y29pbiBhZGRyZXNzOiBudWxsPC9iPjwvZm9udD4KCi0tLS0tClRoYW5rIHlvdSwKUGF5bWVudHMubmV0PC9wcmU+CjwvYm9keT4KPC9odG1sPgo="
}

Новый

POST /api/v1/account/new

Зарегистрировать нового пользователя.

Параметры: Строка запроса, Тело запроса

Добавить

POST /api/v1/account/add

Добавить данные в учётную запись пользователя.

Параметры: Строка запроса, Тело запроса

Обновить

POST /api/v1/account/update

Обновить данные в учётной записи пользователя.

Параметры: Строка запроса, Тело запроса

Удалить

POST /api/v1/account/delete

Удалить учётную запись пользователя.

Параметры: Строка запроса, Тело запроса

Сделка

Создать

POST /api/v1/deal/create

Создать сделку.

Параметры: Строка запроса, Тело запроса

Оплатить

POST /api/v1/deal/pay

Оплатить сделку.

Параметры: Строка запроса, Тело запроса

Завершить

POST /api/v1/deal/complete

Завершить сделку.

Параметры: Строка запроса, Тело запроса

Примеры:

  • HTTP Request:
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 "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:
POST /api/v1/account/new HTTP/1.1
Host: localhost:4999
Content-Type: application/json

{"address": "mynFyJJkRhsbB6y1Q5kTgDGckVz2m9NKH8", "key":  "02ef68c191984433c8a730b8fa48a47ec016a0727e6d26cc0982c8900b39354f61"}
  • curl command:
curl "http://localhost:4999/api/v1/account/new?payload=html" \
  -X POST \
  -d '{"address": "mynFyJJkRhsbB6y1Q5kTgDGckVz2m9NKH8", "key":  "02ef68c191984433c8a730b8fa48a47ec016a0727e6d26cc0982c8900b39354f61"}' \
  -H "Content-Type: application/json"
  • HTTP Request:
POST /api/v1/account/new?payload=html HTTP/1.1
Host: localhost:4999
Content-Type: text/plain

mynFyJJkRhsbB6y1Q5kTgDGckVz2m9NKH8
02ef68c191984433c8a730b8fa48a47ec016a0727e6d26cc0982c8900b39354f61
  • curl command:
curl "http://localhost:4999/api/v1/account/new?payload=html" \
  -X POST \
  -d "mynFyJJkRhsbB6y1Q5kTgDGckVz2m9NKH8\n02ef68c191984433c8a730b8fa48a47ec016a0727e6d26cc0982c8900b39354f61" \
  -H "Content-Type: text/plain"
  • 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);
});
Reference in New Issue View Git Blame Copy Permalink