Версии REST API приложения ASP.NET MVC

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

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

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

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

Ответ 1

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

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

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

Ответ 2

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

Либо вы сможете различать, какую версию вызывается.