RESTful API

Что это такое

RESTful API выставляет данные как ресурсы со стабильными адресами, а клиенты действуют над ними, опираясь на стандартные значения методов HTTP и кодов состояния. У коллекции есть адрес, у отдельного элемента — дочерний, а создание, чтение, замена и удаление отображаются на методы, которые протокол уже определяет; стиль этот — набор ограничений, а не спецификация, и следовать стоит тем его частям, которые делают API предсказуемым для того, кто не читал его документацию.

Почему это важно

Предсказуемость и есть вся отдача: когда каждый API придумывает собственные глаголы и формат ошибок, каждая интеграция превращается в разведку, а у клиентов накапливаются особые случаи. Когда соглашения соблюдены, тот, кто знает один эндпоинт, знает и форму остальных — как перечислить ресурсы, как получить один, как создать и как выглядит сбой. Однако от соглашений зависят не только люди: чтение, которое меняет состояние, или создание, повтор которого даёт другой результат, ломают допущения, на которые опираются кэши и прокси.

Что в этом треке

1. Ресурсы, методы и коды состояния (05-backend-data/06-restful-api/01-resources-verbs-and-status-codes) — правила проектирования и причина существования каждого.
2. Версионирование, пагинация и ответы N+1 (05-backend-data/06-restful-api/02-versioning-pagination-and-n-plus-one) — режимы отказа, которые появляются, когда у API есть настоящие клиенты и настоящие данные.

Предварительные требования

Нет.

Что читать дальше

• Проектирование API (OpenAPI / Swagger) (05-backend-data/09-api-design-openapi-swagger) — как эти правила записывают и проверяют до реализации.
• Аутентификация и авторизация (OAuth2 / JWT) (05-backend-data/10-authentication-authorization-oauth2-jwt) — кому можно вызывать эти эндпоинты и как они это доказывают.
• WebSockets (05-backend-data/11-websockets) — случай, когда «запрос — ответ» — совершенно неподходящая форма.