Проектирование Web API

Одним из самых распространенных подходов при проектировании API является REST API, что такое REST API можно узнать здесь.

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

Перейдем к принципам, поскольку для REST используется протокол HTTP, то он силньо завязан на его особенностях и в частности на адресе URL.

URL

Чтобы ваш API было легче понимать уделите особое внимание идентификаторам ваших ресурсов(URI):

  1. делайте минимальными и понятными(краткое название ресурса);
  2. абстрактные ресурсы лучше заменить на конкретные(/videos вместо /items)
  3. не используйте в них глаголы, вместо них используйте HTTP методы (POST, PUT, GET, PATCH, DELETE);
  4. используйте в названии только множественное или только единственное число для ресурсов во всем проекте;
  5. используйте не более двух адресов на один ресурс (/videos и /videos/{id});
  6. для вложенных ресурсов используйте URL вида /videos/{id}/comments;
  7. используйте простые и прозрачные имена в параметрах запросов после знака “?”;

Ошибки

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

Версии

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

Пагинация и поля ответа

Испольуйте для пагинации параметры limit и offset, не забывайте возвращать в ответе общее количество доступных ресурсов.

Клиентам не всегда нужны все доступные поля, потому предусмотрите возможность кастомизации списка возвращаемых полей параметром fields.

Параметр fields может содержать одно и более названий полей, перечисленных через запятую, эта возможность бывает полезной для сложных ресурсов с большим количеством метаданных.

API субдомен

Выделите для вашего API отдельный субдомен(например api.example.com/v{version_id}) и сосредоточьте все ваше API в зоне этого субдомена.

Формат

Для передачи формата входных и получаемых данных указывайте формат в виде расширения файла(например /v1/videos.json) и обеспечьте поддержку нескольких форматов данных.

Интеграция и документация

Напишите SDK или библиотеки для платформ, которые используют ваши клиенты. Cопроводите это все качественными и подробными примерами использования вашего API и документацией по использованию ваших инструментов и API.

Leave a Reply

Your email address will not be published. Required fields are marked *