Сервисы используют методы GET, POST и PUT, отвечающие стандарту RFC 7231. Путь к сервису должен соответствовать шаблону «api/[version]/[controller]», например, «api/v1/metering_devices». Тело запроса содержит json-объект, соответствующий описанию сервиса, наименования свойств объектов формируются по правилам snake_case. Свойства со значениями по умолчанию исключаются из сериализации. Все операции по лицевым счетам проводятся исключительно по соответствующим платежным кодам. Все запросы должны быть авторизованы, ограничения по данным накладываются в разрезе платежного кода.
Требования к методу | |||
| GET | POST | PUT |
Имеет тело запроса | Нет | Да | Да |
Имеет тело ответа | Да | Да | Нет |
Безопасный | Да | Нет | Нет |
Идемпотентный | Да | Нет | Да |
Обращения к сервисам доступны только по HTTPS протоколу. Аутентификация сторонней системы производится самоподписным доверенным сертификатом на уровне nginx.
Аутентификация конечного пользователя производится методом передачи заголовка Authorization (используется базовая аутентификация) на уровне прикладной системы. Для базовой авторизации пользователя предлагается использовать платежный код в качестве имени пользователя и результат слияния фамилии и номера квартиры через разделитель “@”.
Пример:
Аутентификация пользователя | |
Построение заголовка | Basic Base64([платежный код]:[фамилия]@[квартира]) Пример для пользователя с фамилией «Иванов», квартирой «64А» и платежным кодом «810123456»: Password = “иванов@64а” Token = “810123456:иванов@64а” Base64String = “ODEwMTIzNDU2OtC40LLQsNC90L7QskA2NNCw” |
Результат | Authorization: Basic ODEwMTIzNDU2OtC40LLQsNC90L7QskA2NNCw |
В качестве ответов для всех сервисов резервируются следующие коды ответов, для каждого из методов набор ошибок может быть расширен:
Зарезервированные коды ответов | |
Код ответа | Описание ответа |
400 (Bad Request) | Запрос подписан неверным сертификатом сторонней системы |
401 (Unauthorized) | Введен неверный платежный код, фамилии или номера квартиры |
403 (Forbidden) | Запрошенные данные недоступны |
404 (Not Found) | Запрошенный объект не найден |
408 (Request Timeout) | Запрос не отработал за отведенный промежуток времени |
422 (Unprocessable entity) | Объект распознан, но не может быть обработан |
В теле ответа неуспешные ответы могут быть дополнены информацией, детализирующей возникшие в процессе обработки ошибки. Тело ответа представляется json массивом объектов и состоит из свойств, описанных в таблице:
Описание объекта ошибки | |||
Свойство | Тип | Описание | |
Id | UInt32 | Идентификатор объекта | |
Code | Int32 | Идентификатор ошибки | |
Comment | String | Детализация ошибки | |
Пример | |||
[ { "id": 500, "code": 10000, "comment": "Целая часть введенного показания превышает разрядность прибора учета" } ] | |||
Перечень сервисов и примеры вызовов см здесь Список сервисов портала Наш дом для голосового робота.docx