API versioning

[snipe]

Hi all,

Are there any plans for built-in API-versioning? I've been looking at https://github.com/dingo/api, and it looks great, though a little overkill for what I need. One thing it does have it smart routing around API versions, to declare which API versions specific routes will work for: https://github.com/dingo/api/wiki/Creating-API-Endpoints

That may be out of scope for what this package is trying to do, but anyone who has written a publicly-consumable API knows how quickly versions can get confusing and end up with regression issues. Would be great if something like that could be built-in here.

[chrisbjr]

Hi @snipe sorry for the super duper late reply. We usually just append the version to the route like so: api/v1/some-resource.

If we want a v2, we create new classes with a different namespace like App\Http\Controllers\Api\V2 and create a corresponding route api/v2/some-resource

I'm sure it's not the optimal way, but it works for us. Dingo has created their own methods that can be used in the routes. I want to consider this but I'm not sure what the benefits are as compared to just creating a new route group with a v2 prefix.

[gholol]

@chrisbjr Dingo is using header approach, while ApiGuard is using URI approach.

There re few pros and cons for the latter, surely it's more flexible and friendly for client devs; It allows testing with a web browser and doesn't force programmer to use programatic approach for it (i.e: It's easier) but it also violates basic REST principles (also HATEOAS) because the URL should represent the entity itself and it shouldn’t change because of a different version

I would be more than happy if we could handle versioning via custom header or Accept-header.

[chrisbjr]

Hi @gholol not so convinced with handling versioning on the header level yet - but it does seem logical since it does make for cleaner URLs. Will leave this issue open and see if we can do this as well