What is the correct project file structure for a versioned rest api?

Question

Should I have resource directories inside version directory, like

app/
 v1/
 book/
 author/
 v2/
 author/

or version directories inside resource folder

app/
 book/
 v1/
 author/
 v1/
 v2/

which one would be easier to maintain and which is commonly used today?

Answer 1

Most common way: I think it is "version first, resources inside". At least I've seen it in APIs of different social networks. And I've never actually seen the other way.

It is the only logical way of two: there are resources inside (different versions of) your API, not APIs inside resources. It is easier to drop older versions that way: just respond with 404 on all subresources' requests, providing a message like "This version of API is no longer exists" - that makes it clear that it is not just a typo in URL. For that reason, I think it is also much easier to maintain, at least in frameworks I've used: I'd just add another rule in my router, which matches all the older versions, and responds properly.

So, in my experience, first version (version first, resources inside) is the only one I've seen being used, and is much easier to maintain.

---

Header-based versioning (e.g. Accept: application/vnd.service.v2+json) is very different from URL nesting: versioning a whole API vs. versioning a single entity. Changes in API may include adding, moving and deleting resources, which is not something you can effectively describe using a version of entity.

Also, REST requires HATEOAS (see Richardson Maturity Model for in-depth explaination of this), which would be difficult (or impossible) to implement with header-based versioning. For example, is it even possible to fit header-based versions into HAL? You'd have to invent a way to add version into links, which would probably require custom format (not URL).

Some people think the opposite is true, but still I disagree, because it is not about versioning resources, but rather versioning the whole API. All resources inside each version of an API have the same version, no matter if those resources are the same as in previous versions.

• ivan.c: However, there is another way: some people prefer to version not service, but resource itself via Accept header (like "Accept: application/vnd.service.v2+json"). That way you can version you "author" resource rather than service at whole in case you need only to rename the field or delete one. I suppose, in that case, the resource first option is more appropriate. What do you think?
• scriptin: @ivan.c I expanded the answer.

Answer 2

I hope you are not confusing the URL pattern, with the file system.

The URL pattern is something flexible and where (and how) your source code is written or structured is completely different.

You should not confuse the two.

As for the convention, it is common to use the version handler before the resource (or collection) name: http://www.example.com/api/v1/books/ for example. This is best practice as demonstrated by most public REST apis. You can also choose to version your API differently; for example api/2014-01/books/ or api/1.0.1/books etc.

The notable exception is facebook which has the version as an optional parameter to the URL, ?v=1.

You should keep the version number as most to the left of the URI as possible, as this gives it the highest scope.

In any case, you should always properly document your API versions and if there is a backwards-incompatible change, document that and give your developers a chance to migrate.

• ivan.c: Sorry for confusion, but I really meant filesystem directory structure.