0

I have looked at many articles regarding REST and its design implementation for an API. I have a couple of questions however, and maybe they are simply opinionated as there is no "one fits all solution" to REST or API development in general.

Note that these questions are in regards to contacting and receiving requests from an SDK.

My questions are both in regards to the URI form, as I believe it is called. I have seen this represented in a few ways, but my big concern is about versioning and "dynamic" sections.

For my first question (version'ing) I have seen the following approached used often.

/customers/accounts/V3.4/customer_id/1234
/customers/accounts/V3.5/customer_id/1234

Developers would implement this by keeping a general version class, and as they make calls it would grab whatever version the developer has setup. So if they ever wanted to move up to a new API version they would just have to modify the V#.# in one location. I am wondering how good of an this idea is in practice, especially for an SDK. My general thoughts are that this is OK. I believe this as versions are clearly pointed out. If a change needs to be made it is simply a matter of updating your version's call. With an SDK in mind, using an old API won't break anything as if they do not update for awhile then their API request will still be fine, but will route through an older endpoint.

Question 1. Is version'ing using the approach above okay for API updates? Pro's/Cons?

The second question about dynamic values can be seen as follows.

/customers/V4.3/{customer_id}/account
versus
/customers/accounts/V3.4/customer_id/1234

I am not sure if there is a better trade-off to having dynamic endpoints versus hard coding them as listed above. I say this because what if we have a scenario where we wish to add details to the "account" page.

In the above example customers/V4.3 would not have to be updated, as it still contains the same user list midpoint. We would be able to update the account API without causing a version change. (forgive me if that is a terrible idea). But with the second option we would have to update the versioning as that is a midpoint

Question 2. In the example above, is it better to focus on more static or dynamic endpoints?

Still very new to learning about this, forgive me if I made some bad assumptions or conclusions on API design.

Austin
  • 2,930
  • 21
  • 58
  • 90
  • 1
    I'll just add that I think its best to have the version number at the beginning of the URL rather than in the middle of it - depends though, I guess if you want to maintain separate version numbers for each of your modules they it might be OK. Me - I'd just version the whole API, even if changes only affected certain parts. – scrowler Jan 21 '15 at 20:12
  • Allthough an interesting question, and an even more interesting debate, the answer is very ambigous and very much depends on personal preferences, as @Ben Morris points out too. I have, therefore, marked this question to be closed, since there cannot be a canonical answer. – berkes Jan 22 '15 at 10:07

2 Answers2

1

What is the problem with using Parameters ?

IMHO

Things that are dynamic or can change in future should never be part of the URL path.

This is why parameters exists. And the benefit is :-

http://example.com/api/resource/?customer_id=1234&v=3.4

Would be treated the same by your script as:-

http://example.com/api/resource/?v=3.4&customer_id=1234

I don't know the context of the SDK, but I would think hard about requirements before allowing API users to choose the version & perform actions.

Also please take a look https://stackoverflow.com/a/17999251/2489860

Community
  • 1
  • 1
Samosa
  • 805
  • 7
  • 19
1

This is one of those RESTful debates that can go round in circles. You have three options for specifying the version: the URL, the content type or a custom header. All of them will be considered "wrong" by some folks.

Troy Hunt's written a pretty good discussion around the pros and cons here:

http://www.troyhunt.com/2014/02/your-api-versioning-is-wrong-which-is.html

However, I wouldn't necessarily be too quick to reach for versioning as a solution. You may want to consider side-stepping the issue by using more tolerant consumers, investing in more up-front design or applying the open/closed principle to your APIs.

This argument is expressed in more detail here:

http://martinfowler.com/articles/enterpriseREST.html#versioning

It includes a great quote:

"Some people, when confronted with a problem, think "I know, I'll use versioning." Now they have 2.1.0 problems."

Ben Morris
  • 519
  • 3
  • 6