Wersjonowanie API dla tras Railsowych

Próbuję zmienić wersję mojego API tak, jak ma to Stripe. Poniżej podano najnowszą wersję API to 2.

/api/users zwraca 301 do /api/v2/users

/api/v1/users zwraca indeks 200 użytkowników w wersji 1

/api/v3/users zwraca 301 do /api/v2/users

/api/asdf/users zwraca 301 do /api/v2/users

Więc w zasadzie wszystko, co nie określa wersji, łączy się z najnowszą wersją, chyba że określona wersja istnieje, a następnie przekierowuje do niej.

Oto, co mam do tej pory:

scope 'api', :format => :json do
  scope 'v:api_version', :api_version => /[12]/ do
    resources :users
  end

  match '/*path', :to => redirect { |params| "/api/v2/#{params[:path]}" }
end

Oryginalna forma tej odpowiedzi jest zupełnie inna i można ją znaleźć tutaj . To tylko dowód, że istnieje więcej niż jeden sposób na oskórowanie kota.

Od tamtej pory zaktualizowałem odpowiedź, aby używać przestrzeni nazw i przekierowań 301 - zamiast domyślnego 302. Dzięki pixeltrix i Bo Jeanes za podpowiadanie tych rzeczy.

Możesz chcieć nosić naprawdę mocny kask, ponieważ to oszaleje .

Interfejs API routingu Rails 3 jest super zły. Aby napisać trasy dla swojego interfejsu API, zgodnie z powyższymi wymaganiami, potrzebujesz tylko tego:

namespace :api do
  namespace :v1 do
    resources :users
  end

  namespace :v2 do
    resources :users
  end
  match 'v:api/*path', :to => redirect("/api/v2/%{path}")
  match '*path', :to => redirect("/api/v2/%{path}")
end

Jeśli po tym momencie twój umysł jest nadal nienaruszony, pozwól mi wyjaśnić.

Po pierwsze, wywołujemy, namespaceco jest bardzo przydatne, gdy chcesz, aby grupa tras obejmowała określoną ścieżkę i moduł o podobnej nazwie. W tym przypadku chcemy, aby wszystkie trasy wewnątrz bloku namespacebyły ograniczone do kontrolerów w Apimodule, a wszystkie żądania do ścieżek wewnątrz tej trasy będą poprzedzone prefiksem api. Prośby takie jak /api/v2/users, wiesz?

Wewnątrz przestrzeni nazw definiujemy jeszcze dwie przestrzenie nazw (woah!). Tym razem mamy do definiowania nazw „v1”, więc tutaj wszystkie trasy dla kontrolerów będzie wewnątrz V1modułu wewnątrz Apimodułu: Api::V1. Definiując resources :userswewnątrz tej trasy, kontroler będzie zlokalizowany pod adresem Api::V1::UsersController. To jest wersja 1 i możesz się tam dostać, wykonując żądania, takie jak /api/v1/users.

Wersja 2 jest tylko maleńki nieco inna. Zamiast kontrolera obsługującego to jest Api::V1::UsersControllerteraz, jest teraz Api::V2::UsersController. Dostajesz się tam, składając prośby takie jak /api/v2/users.

Następnie matchużywany jest. Spowoduje to dopasowanie wszystkich tras API, które prowadzą do rzeczy takich jak /api/v3/users.

To jest ta część, na którą musiałem spojrzeć. :to =>Opcja pozwala na określenie, że wniosek powinien zostać przekierowany specyficzny gdzieś indziej - Wiedziałem, że dużo - ale nie wiem jak zrobić to przekierować do innego miejsca i przekazać w kawałku pierwotnego wniosku wraz z nim .

Aby to zrobić, wywołujemy redirectmetodę i przekazujemy jej ciąg znaków ze specjalnym %{path}parametrem interpolowanym . Kiedy przychodzi żądanie, które pasuje do tego końcowego match, interpoluje pathparametr do lokalizacji %{path}wewnątrz ciągu i przekierowuje użytkownika do miejsca, w którym musi się udać.

Na koniec używamy innego matchdo kierowania wszystkich pozostałych ścieżek z prefiksem /apii przekierowywania do nich /api/v2/%{path}. Oznacza to, że żądania takie jak /api/userstrafią do /api/v2/users.

Nie mogłem wymyślić, jak się /api/asdf/usersdopasować, ponieważ jak określisz, czy to ma być prośba o /api/<resource>/<identifier>czy /api/<version>/<resource>?

W każdym razie było to fajne badanie i mam nadzieję, że ci pomoże!

Kilka rzeczy do dodania:

Twoje dopasowanie przekierowania nie zadziała na niektórych trasach - *apiparametr jest chciwy i pochłonie wszystko, np. /api/asdf/users/1Przekieruje do /api/v2/1. Lepiej byłoby użyć zwykłego parametru, takiego jak :api. Wprawdzie nie będzie pasować do przypadków takich jak, /api/asdf/asdf/users/1ale jeśli masz zagnieżdżone zasoby w swoim api, jest to lepsze rozwiązanie.

Ryan DLACZEGO NIE LUBISZ namespace? :-), np .:

current_api_routes = lambda do
  resources :users
end

namespace :api do
  scope :module => :v2, &current_api_routes
  namespace :v2, &current_api_routes
  namespace :v1, &current_api_routes
  match ":api/*path", :to => redirect("/api/v2/%{path}")
end

Co ma dodatkową zaletę w postaci wersjonowanych i ogólnych nazwanych tras. Dodatkowa uwaga - konwencja podczas używania :modulepolega na używaniu notacji podkreślenia, np .: api/v1nie „Api :: V1”. W pewnym momencie ta ostatnia nie działała, ale wydaje mi się, że została naprawiona w Railsach 3.1.

Ponadto, gdy wydasz wersję 3 swojego API, trasy zostaną zaktualizowane w następujący sposób:

current_api_routes = lambda do
  resources :users
end

namespace :api do
  scope :module => :v3, &current_api_routes
  namespace :v3, &current_api_routes
  namespace :v2, &current_api_routes
  namespace :v1, &current_api_routes
  match ":api/*path", :to => redirect("/api/v3/%{path}")
end

Oczywiście jest prawdopodobne, że Twój interfejs API ma różne trasy między wersjami, w takim przypadku możesz to zrobić:

current_api_routes = lambda do
  # Define latest API
end

namespace :api do
  scope :module => :v3, &current_api_routes
  namespace :v3, &current_api_routes

  namespace :v2 do
    # Define API v2 routes
  end

  namespace :v1 do
    # Define API v1 routes
  end

  match ":api/*path", :to => redirect("/api/v3/%{path}")
end

Jeśli to w ogóle możliwe, sugerowałbym przemyślenie swoich adresów URL, tak aby wersja nie była w adresie URL, ale została umieszczona w nagłówku accept. Ta odpowiedź na przepełnienie stosu pasuje do tego dobrze:

Najlepsze praktyki dotyczące wersjonowania API?

a ten link pokazuje dokładnie, jak to zrobić z routingiem rails:

http://freelancing-gods.com/posts/versioning_your_ap_is

Nie jestem wielkim fanem wersjonowania trasami. Stworzyliśmy VersionCake, aby wspierać łatwiejszą formę wersjonowania API.

Umieszczając numer wersji API w nazwie pliku każdego z naszych odpowiednich widoków (jbuilder, RABL itp.), Utrzymujemy wersjonowanie dyskretne i pozwalamy na łatwą degradację w celu wsparcia kompatybilności wstecznej (np. Jeśli widok v5 nie istnieje, możemy render v4 widoku).

Nie jestem pewien, dlaczego chcesz przekierować do określonej wersji, jeśli wersja nie jest wyraźnie wymagana. Wygląda na to, że chcesz po prostu zdefiniować domyślną wersję, która będzie wyświetlana, jeśli żadna wersja nie zostanie wyraźnie zażądana. Zgadzam się również z Davidem Bockiem, że utrzymywanie wersji poza strukturą adresu URL jest czystszym sposobem obsługi wersjonowania.

Shameless plug: Versionist obsługuje te przypadki użycia (i nie tylko).

https://github.com/bploetz/versionist

Odpowiedź Ryana Bigga zadziałała dla mnie.

Jeśli chcesz również zachować parametry zapytania przez przekierowanie, możesz to zrobić w następujący sposób:

match "*path", to: redirect{ |params, request| "/api/v2/#{params[:path]}?#{request.query_string}" }

Zaimplementowałem to dzisiaj i znalazłem to, co uważam za „właściwą drogę” na RailsCasts - REST API Versioning . Tak prosty. Tak łatwe do utrzymania. Tak skuteczny.

Dodaj lib/api_constraints.rb(nie musisz nawet zmieniać vnd.example.)

class ApiConstraints
  def initialize(options)
    @version = options[:version]
    @default = options[:default]
  end

  def matches?(req)
    @default || req.headers['Accept'].include?("application/vnd.example.v#{@version}")
  end
end

Konfiguracja config/routes.rbtaka jak ta

require 'api_constraints'

Rails.application.routes.draw do

  # Squads API
  namespace :api do
    # ApiConstaints is a lib file to allow default API versions,
    # this will help prevent having to change link names from /api/v1/squads to /api/squads, better maintainability
    scope module: :v1, constraints: ApiConstraints.new(version:1, default: true) do
      resources :squads do
        # my stuff was here
      end
    end
  end

  resources :squads
  root to: 'site#index'

Edytuj swój kontroler (tj. /controllers/api/v1/squads_controller.rb)

module Api
  module V1
    class SquadsController < BaseController
      # my stuff was here
    end
  end
end

Następnie możesz zmienić wszystkie linki w swojej aplikacji z /api/v1/squadsna /api/squadsi ŁATWO wdrażać nowe wersje API bez konieczności zmiany linków