У нас есть веб-приложение, которое размещено с URL http://example.com. Теперь мы хотим расширить часть этого приложения в качестве успокоительной службы, и мы обсуждаем лучший шаблон URL. Я искал, но не мог найти никакого конкретного руководства.
Должен ли мы иметь шаблон URL http://api.example.com или http://exaple.com/api/v1?
Есть ли для этого стандартное руководство?
Это зависит от ваших потребностей.
Если вы используете http://api.example.com, это делает ваш API субдоменом. В принципе, этот шаблон URL хорош, если ваша служба REST должна потребляться несколькими клиентами, но если к вашему API подключен только один клиент, тогда шаблон http://example.com/api/v1 - это хорошо. Однако, если вы хотите добавить больше API с большим количеством клиентов, подключенных к нему, лучше использовать http://example.com/api/v1. Например, рассмотрим следующее.
http://example.com/reportapi/apioperation?parameters
http://example.com/paymentapi/apioperation?parameters
http://example.com/searchapi/apioperation?parameters
И последнее, но не менее важное: PayPal использует шаблон http://example.com/api/v1.
Думаю, вам не стоит использовать ни http://api.example.com, ни http://example.com/api/v1.
Вместо этого я бы предложил использовать http://example.com/api и согласование содержимого для версий.
Вот мои мысли, почему:
Использование субдомена:
В URI Scheme Specification вы определяете API в части полномочий URI, которая используется для определения вашего хоста, а скорее чем определение приложения или API на вашем хосте. Фактически вы создаете другой адрес для вашего API, что означает, что аутентификация может не работать на api.example.com, как это делается для example.com.
Действительной причиной этого может быть создание нового экземпляра для мобильных устройств, например. mobile.example.com, но я бы рассматривал это скорее как инфраструктурное решение, а не функциональное.
Использование неверсированного пути в главном домене:
Здесь есть два бита информации: один указывает, что есть ресурс API, а второй - номер версии этого ресурса API (v1).
Нет ничего плохого в использовании /api/ для разграничения между API и, например, вашего веб-представления, которое может работать под /web/. Это можно считать общей наилучшей практикой.
Я не уверен, что вы намеревались это сделать, но ваш вопрос включает в себя запрос о том, как разрешить управление версиями API. Лично я считаю, что управление версиями API не должно выполняться с использованием URL-адресов, поскольку они должны оставаться стабильными как можно дольше. Классные URI не меняются! Вместо этого рассмотрите возможность использования информации HTTP Content-Type для версии вашего API. Я действительно нашел этот метод, используемый в документации VMware. Кроме того, здесь приведена довольно старая, но все же полезная публикация о типе контента типа Peter Williams.
Это случай компромиссов без единого наилучшего решения.
Например, если ваш http://example.com/ предоставляет контент через стандартный веб-интерфейс, а также через API, вам нужно что-то вроде http://api.example.com/api/<version>/<the usual resource pattern>
просто для того, чтобы отделить доступ к API на основе браузера от взаимодействия с API. Это имеет смысл?
Пример: api.rottentomatoes.com
Однако, даже если ваш домен предназначен для вызовов API, имеет смысл использовать вышеприведенный шаблон в любом случае и зарезервировать http://example.com/ для других способы взаимодействия с вашим приложением. Например, вы можете захотеть http://example.com/mobile/ и т.д.