REST API управления версиями приложения ASP.NET MVC

Question

Я смотрю на разработку приложения в ASP.NET MVC 3 и хотел бы одновременно предоставить публичный API.

При осмотре вокруг, кажется, есть 2 способа сделать это. Либо создайте область API и имейте контроллеры, которые возвращают json / xml. Или используйте фильтры действий и один набор контроллеров переднего плана, и они возвращают json / xml / html в зависимости от заголовков запроса.

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

Если вы пойдете первым путем, вы можете легко создать контроллер v1 / v2, но если вы сделаете позже, как вы могли бы его версии?

Answer 1

Управление версиями - довольно сложный вопрос для начала. Вот способы, на которые я смотрел раньше:

1. URL . В этом случае https://api.example.com/v1/projects считается ресурсом, отличным от http://api.example.com/v2/projects,, даже если это не так. Basecamp , кажется, делает это. Следуя этому подходу, предположим, что вам всегда придется поддерживать старые API.
2. Headers . URL-адреса остаются прежними, однако клиент передает дополнительный заголовок HTTP, скажем, X-MYAPI-VERSION, с каждым запросом со значением, определяющим версию используемого API. API Списка документов Google делает это. Потенциальная проблема этого подхода заключается в том, что заголовки HTTP могут быть удалены посредниками между клиентом и сервером.
3. Параметры . Чтобы обойти проблему с вариантом 2, вы можете передать версию API для использования в качестве параметра (например, https://api.example.com/projects?v=3).
4. Типы носителей . Здесь ваши URL остаются прежними, однако пользователи должны указывать представление ресурсов, используя заголовки типа accept и content. Например, «проект» может быть представлен с использованием «application / vnd.mycompany.resource [-version] [+ format]», предоставляя ваши представления «application / vnd.mycompany.project-v1 + json» для v1 json или » application / vnd.mycompany.project-v1 + xml "для v1 xml. Когда вам нужна новая версия проекта, MIME-тип может выглядеть следующим образом: «application / vnd.mycompany.project-v2 + xml». Github , кажется, поддерживает это.
5. Часть полезной нагрузки . В этом случае полезная нагрузка запроса содержит номер версии для использования. Например, при передаче XML вы можете посмотреть на пространство имен, чтобы определить, какая версия API используется. Для JSON вы можете использовать свойство "$ version" или "_version" для указания версии.
6. Ключ клиента . Когда приложение зарегистрировано, оно указывает, какую версию API оно хочет использовать. Когда вы аутентифицируете клиента, вы гарантируете, что имитируете версию, которую он хочет использовать.
7. Нет явного управления версиями Всегда есть возможность не создавать версии вашего API и пытаться прозрачно обрабатывать изменения, делая все поля необязательными, и обрабатывать их соответствующим образом, если они отсутствуют. Скорее всего, вы будете делать это в любом случае, чтобы будущие версии вашего API были совместимы с версией, которую вы разрабатываете сегодня.

Многие рекомендуют вариант 4, хотя это не всегда практично. Большинство из этих параметров требуют дополнительной работы для работы с ASP.NET MVC.

Answer 2

Вы можете пойти одним из двух маршрутов - вы можете включить в маршрут API (вместо http://app.lication/category/1 у вас будет что-то вроде http://app.lication/api/v1/category/1) или вы можете включить пользовательский заголовок HTTP .

Любой из них позволит вам определить, какая версия вызывается.