Модуль для Апостол CRM.
-
Сервер приложений (HTTP-сервер, RESTful-сервер) разработан на C++ с применением асинхронной модели программирования на базе epoll API с прямым доступом к СУБД PostgreSQL (через библиотеку: libpq) специально для высоконагруженных систем.
-
Используется для удалённого вызова процедур с применением архитектурного стиля REST (от англ. Representational State Transfer — передача состояния представления).
Следуйте указаниям по сборке и установке Апостол CRM
- Базовая конечная точка (endpoint): localhost:8080
- Все конечные точки возвращают
JSON-объект
- Все поля, относящиеся ко времени и меткам времени, указаны в миллисекундах.
- 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
.
- Параметры могут быть отправлены в любом порядке.
Доступ к API возможен только при наличии маркера доступа или цифровой подписи методом HMAC-SHA256.
Маркера доступа (access_token
) ДОЛЖЕН присутствовать в HTTP заголовке Authorization
каждого запроса.
Формат:
Authorization: Bearer <access_token>
Маркера доступа - это JSON Web Token
RFC 7519.
Выдается он сервером авторизации, роль которого выполняет сама же система.
Пример запроса:
- http request:
GET /api/v1/whoami HTTP/1.1
Host: localhost:8080
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiIDogImFjY291bnRzLnNoaXAtc2FmZXR5LnJ1IiwgImF1ZCIgOiAid2ViLXNoaXAtc2FmZXR5LnJ1IiwgInN1YiIgOiAiZGZlMDViNzhhNzZiNmFkOGUwZmNiZWYyNzA2NzE3OTNiODZhYTg0OCIsICJpYXQiIDogMTU5MzUzMjExMCwgImV4cCIgOiAxNTkzNTM1NzEwfQ.NorYsi-Ht826HUFCEArVZ60_dEUmYiJYXubnTyweIMg
Вместо HTTP заголовка Authorization
можно использовать подпись.
Для передачи данных авторизации в виде подписи используются следующие HTTP заголовки:
Session
- ключ сессии;Nonce
- данное время в миллисекундах;Signature
- подпись.
Примеры:
Пример создания подписи на JavaScript (без данных в теле сообщения)
// CryptoJS - Standard JavaScript cryptography library
const body = null;
const Session = localStorage.getItem('Session'); // efa885ebde1baa991a3c798fc1141f6bec92fc90
const Secret = localStorage.getItem('Secret'); // y2WYJRE9f13g6qwFOEOe0rGM/ISlGFEEesUpQadHNd/aJL+ExKRj5E6OSQ9TuJRC
const Path = '/whoami';
const Nonce = (Date.now() * 1000).toString(); // 1589998352818000
const Body = JSON.stringify(body); // if body === null then Body = "null" <-- string
const sigData = `${Path}${Nonce}${Body}`; // /whoami1589998352818000null
const Signature = CryptoJS.HmacSHA256(sigData, Secret).toString(); // 91609292e250fc30c48c2ad387d1121c703853fa88ce027e6ba0efe1fcb50ba1
let headers = new Headers();
headers.append('Session', Session);
headers.append('Nonce', Nonce);
headers.append('Signature', Signature);
headers.append('Content-Type', 'application/json');
const init = {
method: 'POST',
headers: headers,
body: Body,
mode: "cors"
};
const apiPath = `/api/v1${Path}`;
fetch(apiPath, init)
.then((response) => {
return response.json();
})
.then((json) => {
console.log(json);
})
.catch((e) => {
console.log(e.message);
});
- openssl command:
echo -n "/whoami1589998352818000null" | \
openssl sha256 -hmac "y2WYJRE9f13g6qwFOEOe0rGM/ISlGFEEesUpQadHNd/aJL+ExKRj5E6OSQ9TuJRC"
(stdin)= 91609292e250fc30c48c2ad387d1121c703853fa88ce027e6ba0efe1fcb50ba1
- curl command:
curl -X POST \
-H "Session: efa885ebde1baa991a3c798fc1141f6bec92fc90" \
-H "Nonce: 1589998352818000" \
-H "Signature: 91609292e250fc30c48c2ad387d1121c703853fa88ce027e6ba0efe1fcb50ba1" \
http://localhost:8080/api/v1/whoami
- http request:
POST /api/v1/whoami HTTP/1.1
Host: localhost:8080
Session: efa885ebde1baa991a3c798fc1141f6bec92fc90
Nonce: 1589998352818000
Signature: 91609292e250fc30c48c2ad387d1121c703853fa88ce027e6ba0efe1fcb50ba1
Пример создания подписи на JavaScript (с данными в теле сообщения)
// CryptoJS - Standard JavaScript cryptography library
const body = {
classcode : 'client',
statecode : 'enabled',
actioncode: 'invite'
};
const Session = localStorage.getItem('Session'); // efa885ebde1baa991a3c798fc1141f6bec92fc90
const Secret = localStorage.getItem('Secret'); // y2WYJRE9f13g6qwFOEOe0rGM/ISlGFEEesUpQadHNd/aJL+ExKRj5E6OSQ9TuJRC
const Path = '/method/get';
const Nonce = (Date.now() * 1000).toString(); // 1589998352902000
const Body = JSON.stringify(body); // <-- JSON string
const sigData = `${Path}${Nonce}${Body}`; // /method/get1589998352902000{"classcode":"client","statecode":"enabled","actioncode":"invite"}
const Signature = CryptoJS.HmacSHA256(sigData, Secret).toString(); // 2b2bf5188ea40dfe8207efec56956b6170bdbc2f0ab0bffd8b50acd60979b09b
let headers = new Headers();
headers.append('Session', Session);
headers.append('Nonce', Nonce);
headers.append('Signature', Signature);
headers.append('Content-Type', 'application/json');
const init = {
method: 'POST',
headers: headers,
body: Body,
mode: "cors"
};
const apiPath = `/api/v1${Path}`;
fetch(apiPath, init)
.then((response) => {
return response.json();
})
.then((json) => {
console.log(json);
})
.catch((e) => {
console.log(e.message);
});
- openssl command:
echo -n "/method/get1589998352902000{\"classcode\":\"client\",\"statecode\":\"enabled\",\"actioncode\":\"invite\"}" | \
openssl sha256 -hmac "y2WYJRE9f13g6qwFOEOe0rGM/ISlGFEEesUpQadHNd/aJL+ExKRj5E6OSQ9TuJRC"
(stdin)= 2b2bf5188ea40dfe8207efec56956b6170bdbc2f0ab0bffd8b50acd60979b09b
- curl command:
curl -X POST \
-H "Session: efa885ebde1baa991a3c798fc1141f6bec92fc90" \
-H "Nonce: 1589998352902000" \
-H "Signature: 2b2bf5188ea40dfe8207efec56956b6170bdbc2f0ab0bffd8b50acd60979b09b" \
-d "{\"classcode\":\"client\",\"statecode\":\"enabled\",\"actioncode\":\"invite\"}" \
http://localhost:8080/api/v1/method/get
- http request:
POST /api/v1/method/get HTTP/1.1
Host: localhost:8080
Session: efa885ebde1baa991a3c798fc1141f6bec92fc90
Nonce: 1589998352902000
Signature: 2b2bf5188ea40dfe8207efec56956b6170bdbc2f0ab0bffd8b50acd60979b09b
{"classcode":"client","statecode":"enabled","actioncode":"invite"}
GET /api/v1/ping
Проверить подключение к REST API.
Параметры запроса: НЕТ
Пример ответа:
{}
GET /api/v1/time
Проверить подключение к REST API и получить текущее время сервера.
Параметры запроса: НЕТ
Пример ответа:
{
"serverTime": 1583495795455
}
Полное описание конечных точек смотрите в репозитории вашего проекта.