Введение⚓︎

Общие сведения об АСНА REST API⚓︎

АСНА REST API предназначен для интеграции со сторонним ПО и построен по принципам REST¹. По мере развития проекта мы будем стараться максимально придерживаться принципов REST, чтобы наш API соответствовал Level 3 Maturity RESTful Services. Для работы с API используется HTTP(S) протокол.

Основным адресом АСНА REST API служит URL: https://api.asna.cloud/ или http://api.asna.cloud/ . Все обращения к API должны идти на этот адрес, дополненный адресом ресурса, к которому вы обращаетесь. Адреса ресурсов, а также разрешенные методы доступа к ресурсам описаны далее в документации.

Основные используемые HTTP методы⚓︎

Метод	Описание
GET	Используется только для получения данных
PUT	Используется для изменения данных, а также для операций upsert
POST	Используется только для добавления новых данных
DELETE	Используется только для удаления данных

Основные коды состояний ответов⚓︎

Успешные²

Код	Название	Описание
200	OK	Запрос прошел успешно и этот запрос не привел к изменению данных
201	Created	Запрос прошел успешно и этот запрос привел к созданию новых данных
202	Accepted	Запрос прошел успешно, но переданные данные требуют отложенной обработки
204	No Content	Запрос прошел успешно, данные удалены

Ошибочные²

Код	Название	Описание
400	Bad Request	Ошибка в передаваемых со стороны клиента данных
401	Unauthorized	Клиент не авторизован для выполнения запросов к API
403	Forbidden	Клиент авторизован, но у него нет прав на выполнение данного запроса
404	Not Found	Был запрошен отсутствующий URL
429	Too Many Requests	С клиента было превышено количество запросов в единицу времени
500	Internal Server Error	Произошла ошибка на стороне API, подробное описание ошибки уходит разработчикам сервисов

В 1С эти коды называются КодСостояния

Версионирование⚓︎

В API сервисах АСНА используется версионирование. Версия API, которую вы используете, указывается в URL при запросах к сервису.

1	`GET /v5/stores HTTP/1.1`

Поддерживаемые, а также устаревшие версии API, вы можете узнать из заголовков api-supported-versions и api-deprecated-versions в каждом ответе от сервиса.

GET /v5/stores/BC164E55-B612-4A04-800B-34CCF10F6858/stocks HTTP/1.1
Host: api.asna.cloud
Content-Type: application/json; charset=utf-8
Date: Sat, 08 Apr 2017 17:47:13 GMT
Server: Microsoft-HTTPAPI/2.0
Transfer-Encoding: chunked
X-Rate-Limit-Limit: 7d
X-Rate-Limit-Remaining: 9947
X-Rate-Limit-Reset: 2017-04-14T09:45:30.1113052Z
api-supported-versions: 5.0

Поддерживаемая версия API указана в документации у каждой операции над ресурсами.

Поддерживаемые форматы данных (media-types)⚓︎

Основным форматом для работы с API является JSON. Для уменьшения объемов передаваемой и принимаемой информации вы можете настроить ваш сериализатор JSON так, чтобы поля, содержащие null или значения по умолчанию, не передавались (мы передаем данные именно в таком виде). Формат данных, передаваемых на сервисы АСНА, указывается в HTTP заголовке Content-Type запроса, для JSON это application/json. Формат, в котором вы хотите получить данные, указывается в заголовке Accept запроса. Кодировка текста - UTF-8.

ВНИМАНИЕ!

Еще раз обращаем особое внимание на то что мы передаем и можем принимать данные в JSON без полей, имеющих значение null или значение по умолчанию для типа данных. Т.е. если какое-то поле имеет значение null или значение по умолчанию (например, для булевого поля false, для целого 0), то его не будет в JSON, который мы вернем. Если ваше ПО или десериализатор не умеет работать с таким JSON, то можно получать его полную версию, добавив заголовок Accept со значением application/x-json-full, но просьба не злоупотреблять этим, так как это сильно увеличивает объемы передаваемых данных.

GET /v5/stores/BC164E55-B612-4A04-800B-34CCF10F6858/stocks HTTP/1.1
Host: api.asna.cloud
Content-Type: application/json; charset=utf-8
Date: Sat, 08 Apr 2017 17:47:13 GMT
Server: Microsoft-HTTPAPI/2.0
Transfer-Encoding: chunked
X-Rate-Limit-Limit: 7d
X-Rate-Limit-Remaining: 9947
X-Rate-Limit-Reset: 2017-04-14T09:45:30.1113052Z
api-supported-versions: 5.0

Компрессия данных⚓︎

При использовании HTTPS протокола не рекомендуется использование gzip компрессии. Это связано с потенциальной возможностью использования уязвимостей SSL в этом случае. Если объем передаваемых или принимаемых данных велик, и передача/прием занимает много времени или не проходит, или вы используете протокол HTTP, вы можете использовать компрессию. За компрессию отвечают HTTP заголовки Content-Encoding и Accept-Encoding.

Поддержка Swagger⚓︎

Помимо данного руководства, сервисы API АСНА предоставляют автоматически генерируемую документацию в формате Swagger³. Вы можете использовать эту возможность для изучения нашего API, а также для автоматического формирования клиентского кода, используя обширный набор коммерческих и бесплатных инструментов. Получить swagger.json можно по адресу https://api.asna.cloud/swagger/v5/swagger.json. Подробнее про работу со Swagger можно прочитать в разделе Тестирование АСНА Web API. АСНА REST API имеет встроенный инструмент для просмотра документации в формате Swagger, которым можно воспользоваться, перейдя по адресу https://api.asna.cloud/swagger. Указанный инструмент позволяет не только просматривать документацию, но и выполнять запросы к API.

Локализация⚓︎

С версии 5 API может возвращать большинство информации об ошибках на русском языке (по умолчанию используется английский). Для этого необходимо добавить в запросы HTTP-заголовок Accept-Language со значением ru. Возможно, не все сообщения имеют перевод на русский язык, если вы столкнулись с такой ситуацией, то сообщите, пожалуйста, службе технической поддержки.

Валидация данных⚓︎

Все, передаваемые в API, данные проходят первичную валидацию (проверку на правильность заполнения данных). В случае, если в передаваемых данных содержится ошибка, то весь пакет отклоняется. При этом API возвращает 400 HTTP статус(код состояния) и подробную информацию об ошибках в теле ответа. Следует иметь в виду, что подробная информация об ошибках возможна только в том случае, если API удалось распарсить передаваемый пакет, в противном случае информация об ошибках несет только общий характер.

Основные этапы валидации

Проверяется соответствие типов данных
Проверяется заполнение обязательных полей
Проверяется корректность заполнения полей, например предельная розничная цена для ЖНВЛС не должна быть меньше розничной или закупочной
Проверяется дублирование ключа, например кода партии в остатках
Дополнительные проверки

Ограничение частоты запросов⚓︎

Для поддержания необходимого уровня сервиса и исключения излишней нагрузки API использует механизмы ограничения частоты запросов с одного IP адреса (rate limiter). Возможная частота запросов либо указана в документации по конкретному методу, либо может быть получена в техподдержке. Кроме того, не стоит делать запросы к API, если вы не собрали никаких данных, например, не было изменений остатков за период, заказов, пр. Если вам необходимо с одного IP отправлять много запросов, по разным аптекам, то напишите в техподдержку АСНА.

Рекомендации по работе с API⚓︎

РЕКОМЕНДАЦИЯ

Сервисы API АСНА расположены в облаке и используют облачные ресурсы, поэтому со стороны клиентов, работающих с API необходимо наличие логики повтора вызова API, в случае возникновения временных (transient errors) ошибок, например, таких как таймауты подключения и т.д.

Логика повтора (retry logic) необходима при работе с любыми ресурсами, расположенными в Интернет (в локальной сети это тоже будет не лишним), так как в любой момент возможна потеря связи, отказ коммутационного оборудования, а также апдейт облачных сервисов или внезапная пиковая нагрузка на них. При этом необходимо понимать, какие ошибки являются временными, а какие нет. Например, таймауты подключения, с высокой долей вероятности, ошибка временная, вызванная нагрузкой или временным отсутствием связи, а 400 статус ответа от сервиса является ошибкой постоянной. Если передаваемый на наши сервисы пакет данных содержит ошибки, то вне зависимости от количества попыток, результат будет тот же, пока передаваемый пакет не будет исправлен. В этом случае, нет смысла повторять запросы с ошибочным пакетом. К постоянным ошибкам относится и 404 статус.

При отсутствии со стороны клиента логики повтора, претензии к работе API, связанные с временной недоступностью, рассматриваться не будут.

Веб-сервисы АСНА, это сложная, распределенная система, и как любая сложная система требует периодического обслуживания, например обновления статистики БД или индексов. Для выполнения этих работ предусмотрено технологическое окно, с 5:00 по 9:00 утра по московскому времени. В это время веб-сервисы сервисы АСНА могут быть доступны частично. Пожалуйста, имейте это в виду при работе над интеграцией с нашими сервисами.

Для решения проблем при возникновении инцидентов, необходимо наличие логирования запросов к API со стороны клиентского ПО, список необходимых данных указан ниже:

Точное время запроса с таймзоной
Полный URL запроса и метод
Все заголовки запроса
Тело запроса, если его размер небольшой
Статус ответа от API
Тело ответа, если его размер небольшой

Representational State Transfer (REST) в переводе — это передача состояния представления. Технология позволяет получать и модифицировать данные и состояния удаленных приложений, передавая HTTP-вызовы через интернет или любую другую сеть. Краткое введение ↩
HTTP статусы. Ссылка ↩↩
Swagger(OpenAPI) это язык описания интерфейсов для REST API, выраженный с помощью JSON. Swagger используется вместе с набором программных средств с открытым исходным кодом для проектирования, создания, документирования и использования веб-сервисов RESTful. Swagger включает автоматизированную документацию, генерацию кода (на многие языки программирования) и генерацию тестовых примеров. Ссылка ↩

Последнее обновление: 17 августа 2021 г. 11:14:40
Созданный: 5 августа 2021 г. 12:36:05