1

Let's assume a web app made of independent modules:

example.com/accounting
example.com/employees
example.com/admin

Next step is adding an API which normally might end like this:

example.com/api/v1/accounting
example.com/api/v1/employees
example.com/api/v1/admin

I worked before like this and it was the most natural thing, but now that each sub-app is a whole unique beast that even have independent deployment operations, this pattern came up as an idea:

example.com/accounting/api/v1
example.com/employees/api/v1
example.com/admin/api/v1/

Are there any downsides between both ways of organizing my API across modules that I should be aware of?

I am trying to think about deployment costs, caching, security... but cannot come up with any clear disadvantage. The only thing that bothers me is my habit of having all api operations under a common root path.

6
  • 3
    Ahh... the restish api versioning problem.
    – user40980
    Apr 7, 2015 at 15:47
  • I was just considering about an urgent edit of my question ;-) but since you quickly got an upvote, I will conduct a scientific experiment by leaving the version numbers there and see how many upvotes or extra comments we get. One more thing to learn from this question! Apr 7, 2015 at 15:51
  • There are several interrelated problems around api endpoints. Grouping, versioning (url? if so where? if not, which header?). I personally haven't found any good answers in my own search, though decided on one that was least bad and didn't offend my sensibilities too much.
    – user40980
    Apr 7, 2015 at 15:57
  • "independent deployment operations" -- if all the applications are completely independent, the question is irrelevant, correct? And if they are not independent, it is better to version at the higher level. Apr 7, 2015 at 21:29
  • 1
    The web app already is an API, and I prefer to use that for all clients. Just specify other criteria in HTTP headers.
    – Kwebble
    Apr 7, 2015 at 22:31

1 Answer 1

1

As mentioned by Frank, it depends on how independent the independent modules are. In the example above, and in real life, there is probably a common dependency for these three endpoints, namely a persistent datastore.

Good API naming communicates with the user of the API. If there is truly no dependency, you should use the second pattern since that implies that the API:s are separate and you could e.g. move one one of the API:s to a new server and URL without affecting the semantics of the API.

But if you have any dependency, you should use the first one. Otherwise you could have the following scenario:

  • Management discovers the virtue of email and decides that all the fax numbers in the db should be replaced by email addresses.
  • You update /employees/api/v1 and bump the version number, /employees/api/v2
  • But the change in the db also forces you to update /admin/api/v1/ to /admin/api/v2/

Now you have to communicate to all your users that they have to use v2 for admin and employees and v1 for accounting. I.e. you have to communicate that there is a dependency between your apis. In that situation it's more clear to have one version number for the entire API.

It's good practice to modularize stuff, but in reality there's usually the giant global dependency called the database to think of.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.