7. Правильно обрабатывайте ошибки

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

8. Применяйте необходимые методы обеспечения безопасности

Мы хотим, чтобы вся связь между клиентом и сервером была защищена, а это значит, что нам нужно постоянно использовать SSL/TLS, без исключений. Кроме того, разрешите аутентификацию через ключи API, которые должны передаваться с помощью пользовательского заголовка HTTP, с указанием истечения срока их действия.

9. Используйте нумерацию страниц

Используйте нумерацию страниц, если нашему API нужно вернуть много данных, так как это сделает наш API готовым к будущим изменениям. Здесь рекомендуется использовать page и page_size.

Например, /products?page=10&page_size=20

10. Управление версиями

Очень важно вести версионирование API с первой версии, так как у наших API могут быть разные пользователи. Это позволит нашим пользователям не зависеть от изменений, которые мы можем сделать в будущем. Версии API могут передаваться через заголовки HTTP или параметры запроса/пути.

Например, /products/v1/4

И не забывайте документировать API, потому что API будет хорош настолько, насколько качественна его документация. Документация должна содержать примеры полных циклов запроса/ответа. Здесь мы можем использовать определение OpenAPI в качестве источника истины.

Если вы хотите начать разработку API, ознакомьтесь со спецификациями Swagger, OpenAPI, Postman или Stoplight.