-
Notifications
You must be signed in to change notification settings - Fork 21
Handle API Versioning #24
Comments
I HATE accept headers for versioning, this is for me a big no-no. They are On Fri, May 31, 2013 at 1:04 AM, Jack Chu [email protected] wrote:
|
I don't have strong feelings on this, but I see many people do. Do you think we can implement this with an opinionated default that users can easily override (so it doesn't get overwritten with every wd_sinatra update)? |
Yes, very simple: we don't add built in support for header versioning :)
|
Ha, I'm on the other side of this. I really don't think versioning belongs in the route. Also, because content type is now set via accept header, you need to deal with it anyhow, so why not also handle versioning with content negotiation? As far as logging, you could always log the accept header, or the pieces you want logged in Sinatra. If API users get confused by the accept header, I don't see how they'll figure out how to set the correct media type. But aside from the versioning method, don't we need to define how to set a version in the WD DSL? If anything so when you generate documentation, the two versions are split up. So if you use versioning in your routes, you don't have v1-v3 documentation all mixed together. I think if you're using v3, you only want to see v3 documentation. I kind of think we should handle versioning like grape does it. Support different methods of versioning, which work off of one DSL. |
On Fri, May 31, 2013 at 8:32 PM, Jack Chu [email protected] wrote:
|
I'm finding the need to support a version-ed API thru the DSL I agree about the header thing Matt ;) Tho I don't like the idea of making a new service just because I hate code duplication of any sort. @kumal - If you want the header support just write a rack middleware to parse the header and modify it to set param[:version] ;) Then define your service spec describe_service ":version/hello_world" do |service|
service.formats :json
service.http_verb :get
service.params do |p|
p.string :version, :required => true, :options => ['v1']
end
end Here some other rack version gems Twitter documentation is by version. :) I think picking your version and then looking at those specific docs is the most logical and expected approach. @mattetti - do you think using the same service for each version of an API tends to lead to more problems than its solving? I guess it probably depends if your modifying the contract of the API itself whether it warrants a new version of the API. describe_service ":version/hello_world" do |service|
service.implementation do
if params[:version] == 'v1'
else
end
end
end
describe_service "v1/hello_world" do |service|
end
describe_service "v2/hello_world" do |service|
end |
@pheino The reasons why I prefer to split the various versions of an API into different implementations is
Code duplication is only a problem if the logic is duplicated, here we have 2 versions of the logic, therefore it's not a duplication it's a safe branching of the logic. This way you know you don't introduce regressions. |
I like @mattetti's approach. |
How do you implement an index list service that doesn't need any params past to it? |
@mattetti @raul
One of the major issues with API frameworks is how versioning is handled. I was wondering what your thoughts were about dealing with versioning in WD.
As far as I can tell this probably needs a separate issue in wd_sinatra. In WD, we'll need to decide what the DSL will look like for defining/namespacing different versions of services.
In wd-sinatra, we'll need to decide how to implement it and how to detect a specific version. IE.
I prefer 1, but have heard a decent case for 2 as well.
The text was updated successfully, but these errors were encountered: