Одним из самых распространенных подходов при проектировании API является REST API, что такое REST API можно узнать здесь.
Я же хочу рассказать о тех принципах, которые помогут сделать ваш API удобным для других разработчиков, т.е. для ваших клиентов.
Перейдем к принципам, поскольку для REST используется протокол HTTP, то он силньо завязан на его особенностях и в частности на адресе URL.
URL
Чтобы ваш API было легче понимать уделите особое внимание идентификаторам ваших ресурсов(URI):
- делайте минимальными и понятными(краткое название ресурса);
- абстрактные ресурсы лучше заменить на конкретные(/videos вместо /items)
- не используйте в них глаголы, вместо них используйте HTTP методы (POST, PUT, GET, PATCH, DELETE);
- используйте в названии только множественное или только единственное число для ресурсов во всем проекте;
- используйте не более двух адресов на один ресурс (/videos и /videos/{id});
- для вложенных ресурсов используйте URL вида /videos/{id}/comments;
- используйте простые и прозрачные имена в параметрах запросов после знака “?”;
Ошибки
Всегда обрабатывайте ошибки и сообщайте о них клиенту, используйте соответствующие коды статуса ответа HTTP, также сопровождайте ошибки описанием в теле ответа, возвращайте внятное текстовое описание ошибки.
Версии
Всегда версионизируйте API, например с помощью префикса /v1 или в заголовках и поддерживайте как минимум две последнии версии. Это позволит вашим клиентам плавно и без проблем переходить на новые версии вашего API.
Пагинация и поля ответа
Испольуйте для пагинации параметры limit и offset, не забывайте возвращать в ответе общее количество доступных ресурсов.
Клиентам не всегда нужны все доступные поля, потому предусмотрите возможность кастомизации списка возвращаемых полей параметром fields.
Параметр fields может содержать одно и более названий полей, перечисленных через запятую, эта возможность бывает полезной для сложных ресурсов с большим количеством метаданных.
API субдомен
Выделите для вашего API отдельный субдомен(например api.example.com/v{version_id}) и сосредоточьте все ваше API в зоне этого субдомена.
Формат
Для передачи формата входных и получаемых данных указывайте формат в виде расширения файла(например /v1/videos.json) и обеспечьте поддержку нескольких форматов данных.
Интеграция и документация
Напишите SDK или библиотеки для платформ, которые используют ваши клиенты. Cопроводите это все качественными и подробными примерами использования вашего API и документацией по использованию ваших инструментов и API.