Веб-API стали очень важной темой в прошлом году. Мы в WeStartU каждый день работаем с разными серверными системами, поэтому мы знаем о важности правильного соглашения об именах для API.
По сути, RESTful API оказывается просто набором URI, HTTP-вызовов этих URI и некоторых JSON и / или XML-представлений ресурсов, многие из которых будут содержать реляционные ссылки.
Каждый ресурс имеет свой собственный адрес или URI - каждая интересная информация, которую может предоставить сервер, отображается как ресурс.
Именование ресурсов, возможно, является наиболее обсуждаемой и наиболее важной концепцией, которую необходимо усвоить при создании понятного, легко используемого API веб-службы. Когда ресурсы названы правильно, API интуитивно понятен и прост в использовании. При плохом исполнении тот же API может показаться нелепым, его сложно использовать и понять.
API RESTful написаны для потребителей. Имя и структура URI должны передавать смысл этим потребителям. Часто бывает трудно понять, какими должны быть границы данных, но, разобравшись с вашими данными, вы, скорее всего, будете готовы нанести удар и что имеет смысл возвращаться в качестве представления вашим клиентам. Дизайн для ваших клиентов, а не для ваших данных.
URI должны следовать предсказуемой иерархической структуре для повышения понятности и, следовательно, удобства использования: предсказуемой в том смысле, что они согласованы, иерархической в том смысле, что данные имеют структуру - отношения. Это не правило или ограничение REST, но оно улучшает API.
Некоторые моменты, которые следует учитывать при написании API:
- Должно быть просто
- Должен быть интуитивно понятным
- Всегда должен быть последовательным
- Следует избегать верблюжьих шапок. Обычно используются строчные буквы.
- Следует использовать тире вместо подчеркивания
- Называя API, считайте его папкой. Следуйте шаблону именования, аналогичному структуре папок.
- Использовать иерархию
- Самым важным моментом, который следует учитывать при разработке API, является сохранение номера версии в API.
Должны ли мы действительно добавлять номер версии в URL-адреса API?
Сохранение номера версии в вашем API, вероятно, является важным шагом при разработке API, но возникает вопрос, зачем нам это нужно? Мы создаем API, чтобы возвращать некоторый ответ JSON или XML, так что какой смысл в номере версии? Хотя может показаться бесполезным поддерживать номер версии, но это действительно важно. Предположим, вы создаете систему с большим количеством API, используемых различными клиентами. Теперь в какой-то момент мы хотим изменить API, и ответ API также изменится. В этом случае вместо изменения API мы должны предпочесть добавить новый API и оставить старый API как есть. Это не сломает клиентское приложение, использующее старый API, у нас есть новый API. Позже в какой-то момент мы можем отказаться от этого API, и это поможет в плавном переходе от старого API к новому. Этот подход полезен, но каждый раз поддержание нового набора URI является сложной задачей, а использование номера версии намного полезнее.
Например, у нас может быть какой-то API, который возвращает список пользователей - v1 / users /
Теперь в какой-то момент мы модифицируем API, поэтому вместо поддержки отдельного URL-адреса мы можем просто увеличить номер версии - v2 / users /
Примеры наименования API
- v1 / users - список пользователей
- v1 / users / 1 - пользователь с идентификатором 1
- v1 / users / 1 / organization - организации, к которым принадлежит пользователь
- v1 / organization - список организаций
- v1 / organization / 1 - Организация №1
- v1 / organization / 1 / users - пользователи для этой организации.
Альтернативой может быть использование строки запроса для фильтрации:
- v1 / users возвращает список всех пользователей
- v1 / users? organization = 123 возвращает список пользователей, связанных с этой организацией.
