The module-appserver from apostoldevel

Сервер приложений

Модуль для Апостол CRM.

Описание

Сервер приложений (HTTP-сервер, RESTful-сервер) разработан на C++ с применением асинхронной модели программирования на базе epoll API с прямым доступом к СУБД PostgreSQL (через библиотеку: libpq) специально для высоконагруженных систем.
Используется для удалённого вызова процедур с применением архитектурного стиля REST (от англ. Representational State Transfer — передача состояния представления).

Установка

Следуйте указаниям по сборке и установке Апостол CRM

Документация

REST API

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

Базовая конечная точка (endpoint): localhost:8080
Все конечные точки возвращают 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.
Параметры могут быть отправлены в любом порядке.

Доступ к API

Доступ к 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

Цифровая подпись методом HMAC-SHA256

Вместо 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
}

Полное описание конечных точек смотрите в репозитории вашего проекта.

apostoldevel / module-appserver Goto Github PK

module-appserver's Introduction

Сервер приложений

Описание

Установка

Документация

REST API

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

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

Коды ошибок

Общая информация о конечных точках

Доступ к API

Маркер доступа

Цифровая подпись методом HMAC-SHA256

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

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

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

module-appserver's People

Contributors

Watchers

Recommend Projects

Recommend Topics

Recommend Org