I'm using Laravel to create a versioned JSON API that I'll then access with AngularJS to populate my pages. Currently I'm returning the JSON using versioned controllers (eventually I plan to implement dependency injection & versioned repositories instead).
I've attempting to namespace my controllers in the format App\Controllers\API\v1.0 but when I visit localhost:800/api/1.0/companies in my browser, where the JSON is returned, I am notified that Class App\Controllers\API\v1.0\CompaniesController does not exist . I'm guessing this is because the . is being interpreted like one of the backslashes? I can make the application function by changing the namespace to App\Controllers\API\v1 or App\Controllers\API\v1\v0 , but the former doesn't allow for proper versioning and the latter seems a bit ... inelegant.
What conventions should I use for my namespaces to adequately version my API? Any advice would be appreciated! :)
APIs should only use major versions externally. Following best practice semantic versioning, major versions change when you introduce backwards-incompatible changes to a project.
If you're just adding features, or modifying existing ones in backwards-compatible ways, then you just do it and your existing consumers are not affected (though, they can then make use of the new changes if they want). Your API can change versions from 1.0.0 to 1.1.0 internally, but the version as exposed to your consumers is still just "v1".
If you're just patching bugs, the same applies. Change from 1.0.1 to 1.0.2 internally, but the API should stay at "v1".
Now, if you rename/remove resources, or do some other drastic changes that will break existing clients, your internal version might go from 1.2.0 to 2.0.0, because breaking backwards compatibility requires a major version change. Because of this, the new major version has to be exposed to your API's consumers as "v2".
So, in keeping with this, both your namespaces and your URLs should reflect only the major version (e.g. "v1"), and you should make sure that you never break backwards-compatibility within a major version.