Перевод статьи «Best Practices: API Design».
Хорошо спроектированные API = довольные разработчики.
Прикладные программные интерфейсы (Application Programming Interfaces, API) — это интерфейсы, облегчающие использование в приложениях данных и ресурсов других приложений. Они жизненно необходимы для успеха продукта или даже компании.
Без API большинства ваших любимых программ попросту не существовало бы. Например, API Google Maps позволяет вам использовать карты Google в вашем мобильном или веб-приложении. Без него вам пришлось бы разрабатывать вашу собственную базу данных с картами! Только представьте, сколько времени это заняло бы.
Почему мы используем API?
- API обеспечивают сторонний доступ к вашим ресурсам.
- API расширяют возможности вашего приложения.
- API позволяют разработчикам повторно использовать логику приложения.
- API «платформонезависимы», т. е., они могут доставлять данные, не оглядываясь на особенности запрашивающей платформы.
В большинстве жизненных сценариев модель данных уже будет существовать, но поскольку мы собираемся обсудить лучшие подходы к проектированию API, давайте начнем с самого начала.
Моделирование и структурирование данных
Моделирование данных с оглядкой на будущий API это первый шаг на пути к его легкому созданию, поддержке и обновлению.
При проектировании API всегда старайтесь использовать общие термины, а не сложную бизнес-терминологию, которая может быть неизвестна за пределами вашей организации.
Ваши API могут использоваться внутри вашей компании, но могут и быть открыты для стороннего использования, чтобы другие разработчики могли применять их в своих проектах. Используя общие термины, исходите из того, что они должны быть понятны этим «другим разработчикам», чтобы они могли побыстрее разобраться с вашим API и его интеграцией в свой продукт.
Представьте, что вы строите портал, где пользователи смогут просматривать информацию по книгам различных авторов. В вашей компании могут использоваться свои, специфические термины, например, Storytellers, creations, series (букв. авторы рассказов, произведения, серии), при том, что имеются в виду Authors, books и series (авторы, книги, серии). Для простоты и чтобы сторонние разработчики могли использовать ваши API, имеет смысл придерживаться более общей терминологии при создании путей API.
https://api.domain.com/authors
https://api.domain.com/authors/{id}/books
Таким образом любой разработчик сможет куда быстрее разобраться, что из себя представляет ваш API.
Написание ресурсо-ориентированных API
Приложения, использующие ваши API, хотят получить доступ к вашим ресурсам. Поддержка иерархии ресурсов поможет лучше структурировать ваш API. Каждый узел в вашем пути, содержащий какой-либо ресурс или коллекцию ресурсов, должен занимать определнное место в иерархии.
Ресурсом может быть отдельный кусочек данных, скажем, информация об авторе (если продолжать использовать пример, приведенный выше). Коллекцией ресурсов в нашем случае может быть список книг, написанных отдельным автором.
Иерархия ресурсов при этом может выглядеть следующим образом:
Base Path -> Authors (collection) -> profile (resource) Base Path -> Authors (collection) -> books (collection) -> book (resource)
В иерархии должно поддерживаться постоянство, чтобы у разработчиков не возникало лишних вопросов при интеграции вашего API и их приложения.
Вот несколько советов по поддержке постоянства и простоты:
- В именах коллекций и ресурсов используйте американский английский (например, color, а не colour).
- Следите за правописанием.
- Используйте более простые, широко употребимые слова, чтобы все было максимально ясно (например, delete, а не remove).
- Если используете те же ресурсы, что и в другом API, используйте ту же терминологию.
- Для коллекций используйте множественные формы (например, authors, books и т. п.).
REST
REST (Representational State Transfer) — это наиболее широко используемый стандарт для отправки HTTP-запросов к API. Суть этого подхода в том, что каждый URL представляет объект.
У API может быть одно из следующих назначений:
- Создание данных.
- Чтение данных.
- Обновление данных.
- Удаление данных.
Да, вы угадали, это CRUD!
Назначения API регулируются набором HTTP-слов, определяющих природу запроса и то, что он должен делать.
Слово GET ассоциируется с получением данных от API. Оно запрашивает представление данных. Запрос GET может включать параметры запроса для фильтрации результатов, полученных от API.
Слово POST связано с отправкой информации к API, в результате чего в базе данных будет создан ресурс.
Слово PUT обычно используется для обновления уже имеющихся на сервере ресурсов.
Слово DELETE служит для удаления ресурса с сервера.
Разбираемся с минорными и мажорными обновлениями
Когда вы не вносите изменений, способных сломать приложение вашего клиента, можно обойтись минорными обновлениями. Речь идет о таких вещах как добавление опциональных полей или включение поддержки дополнительных параметров. В таких случаях вы инкрементируете номер минорной версии вашего API.
Мажорные обновления с большей вероятностью способны сломать приложение. К таким обновлениям можно отнести добавление нового обязательного параметра в полезную нагрузку запроса или изменения полей в ответе.
Есть несколько способов версионирования ваших API.
Самый распространенный способ — включение версии в URI.
https://api.domain.com/v1.0/authors
В основе следующего способа лежит дата. При этом в URI включается дата выпуска версии. Преимущество этого способа в том, что любой разработчик сможет сразу увидеть, насколько часто вы обновляете ваш API.
https://api.domain.com/2020-06-15/authors
Третий способ — включение версии API в заголовки.
https://api.domain.com/authors x-api-version: v1
Самый рекомендуемый и приемлемый вариант версионирования — использовать имя версии в URI.
Разбивка на страницы
В мире все возрастающего количества точек данных становится нереальным отображать все данные на одном экране одновременно. Поэтому важно дать возможность пользователям получать определенное количество документов, прежде чем запрашивать новые. Это называется разбивкой на страницы (или пагинацией), а возвращаемый набор данных называется страницей.
Чтобы сделать возможной разбивку на страницы в вашем API, рекомендуется использовать особые фразы в полезной нагрузке запроса и ответа:
- STRING
page_token(отправляется в запросе) - STRING
next_page_token(возвращается API) - INT
page_size(отправляется в запросе)
page_token указывает, какую именно страницу должен вернуть API. Обычно это строка. Для первого вызова API page_token = “1”.
page_size определяет, сколько записей должно вернуться в ответе. Например, page_size = 100 вернет максимум 100 записей по одному вызову API.
next_page_token определяет следующий токен в серии. Если после page_token="1" есть дополнительные данные, возвращается значение next_page_token=”2”. Если же данных больше нет, т. е., пользователь исчерпал их до конца, возвращается пустое значение next_page_token=””.
Вот и все! Это были лучшие подходы, благодаря которым ваши API будут надежными, последовательными и простыми в интеграции с другими приложениями.
[customscript]techrocks_custom_after_post_html[/customscript]
[customscript]techrocks_custom_script[/customscript]