Quelles sont les meilleures pratiques pour la conception d'une API publique RESTful sur Rails?

Question

Rails est livré avec des ressources RESTful prêtes à l'emploi, mais les utilisez-vous pour votre API publique réelle? Si tel est le cas, comment procéderiez-vous à la gestion des versions de votre API, par exemple exemple.com/api/v2/foo/bar ?

Answer 1

En règle générale, les API de mes applications reposent bien sur les mêmes ressources que l’interface HTML. Pour certains (pas moi), cela peut être juste en utilisant le code qui sort du générateur d'échafaudage - mais que je l'écrive ou le laisse personnalisé, il y a très peu de cas où j'expose des ressources uniquement à la programmation API et non à la vue de l'utilisateur final.

La gestion des versions n'a pas posé de problème pour les applications que j'ai construites jusqu'à présent, mais je peux penser à deux façons de l'implémenter.

1) Vous pouvez ajouter des routes avec le préfixe 'v1,' 'v2,' etc. définissant un paramètre auquel vous pouvez accéder dans le contrôleur pour spécifier le traitement à appliquer:

dans routes.rb:

map.resources :posts, :path_prefix => '/:version'

dans posts_controller.rb

class PostsController < ApplicationController
  def index
    respond_to do |format|
      format.xml do
        if params[:version] == 'v1'
          # ...
        else
          # ...
        end
      end
    end
  end
end

2) Vous pouvez également envisager d’ajouter un format de réponse personnalisé pour chaque version

dans initializers / mime_types.rb

Mime::Type.register_alias "application/xml", :v1
Mime::Type.register_alias "application/xml", :v2

dans posts_controller.rb

class PostsController < ApplicationController
  def index
    respond_to do |format|
      format.v1 do
        # ...
      end
      format.v2 do
        # ...
      end
    end
  end
end

Le premier vous donnerait des URL comme example.com/v1/posts.xml et example.com/v2/posts.xml; ce dernier vous donnerait des URL comme example.com/posts.v1 et example.com/posts.v2