Как описать АПИ? (шаг 1)

Контракт API

Контракт API - это формальное описание того, как взаимодействовать с веб-службой или API. Этот контракт определяет, какие запросы могут быть сделаны, какие данные ожидаются в ответе, и какие методы и эндпоинты доступны. Контракт API чаще всего описывается в форме спецификации, такой как OpenAPI (Swagger), RAML, или WSDL (в случае SOAP).

Контракт API включает в себя:

1. Методы и URL-адреса (Endpoint). Определяет, какие HTTP-методы (GET, POST, PUT, DELETE и т. д.) доступны и какие URL-адреса нужно использовать для взаимодействия с API.
2. Параметры запроса. Описывает, какие параметры нужно отправить в запросе (например, в виде пути, строки запроса, или тела запроса).
3. Формат ответа. Указывает, какие данные ожидаются в ответе от API, например, в формате JSON или XML.
4. Авторизация. Определяет, какой тип аутентификации и авторизации необходим для доступа к API.
5. Ошибки и коды состояния. Описывает возможные ошибки и коды состояния, которые могут быть возвращены API.
6. Примеры запросов и ответов. Предоставляет примеры конкретных запросов и ответов, чтобы помочь разработчикам правильно взаимодействовать с API.

Разница между протоколами SOAP и REST:

SOAP (Simple Object Access Protocol) и REST (Representational State Transfer) - это два различных подхода к созданию и взаимодействию с веб-службами.

SOAP

1. Протокол: SOAP является протоколом, определенным стандартами;
2. Соглашение: SOAP требует жесткого соглашения между клиентом и сервером (через WSDL);
3. Формат данных: SOAP использует XML для обмена данными;
4. Транспорт: SOAP может работать поверх различных транспортных протоколов, включая HTTP, SMTP, и другие;
5. Сложность: SOAP-сервисы часто более сложны и тяжеловесны в сравнении с REST.

REST

1. Архитектурный стиль: REST основан на архитектурных принципах и не описывает жестких стандартов;
2. Соглашение: REST полагается на соглашения, но не требует строгих формальных документов, как WSDL;
3. Формат данных: REST может использовать различные форматы данных, такие как JSON, XML и другие;
4. Транспорт: REST обычно работает поверх HTTP;
5. Простота: REST часто считается проще и более гибким в сравнении с SOAP.

Влияние на контракт REST и SOAP

• SOAP имеет жесткий контракт, описанный в WSDL, что делает его более формализованным и строгим.
• REST имеет менее строгие соглашения и, следовательно, более гибкий контракт, который может быть менее формализованным.
• Это означает, что контракт для SOAP более детализирован и формальный, в то время как контракт для REST может быть более свободным и гибким в зависимости от того, как разработчики решают его определить.