10

I am designing a REST API for a web application. I want to clearly version the API, so that the interface can be changed in the future without breaking existing services. So in my v1.0 API, I want to clearly identify it as the v1.0 API, leaving me the freedom to release a future v1.1 version with breaking changes.

My question is, would a period in the path component of a URI be bad practice?

eg. Is there any good reason not to use http://example.com/myapi/v1.0/services as a URI to my service?

Ajoy
  • 1,838
  • 3
  • 30
  • 57
saille
  • 9,014
  • 5
  • 45
  • 57

5 Answers5

12

Putting a period in the URI is perfectly fine. Putting a version number in an URI is definitely not a best practice.

Here are my reasons why and here is an good article on the subject by someone much smarter than me.

Community
  • 1
  • 1
Darrel Miller
  • 139,164
  • 32
  • 194
  • 243
  • Thanks again Darren. Via your link, Shonzilla's answer to this question: http://stackoverflow.com/questions/389169/best-practices-for-api-versioning has convinced me that versioning is probably a bad idea. One concern I have tho is whether a non-browser client, e.g. a PHP website consuming my service will handle a http redirect, if I was to use that approach to handling breaking changes? – saille Apr 20 '10 at 22:46
4

It is perfectly acceptable to use a period in a URI path. It is also valid as per RFC 3986 section 2.3.

Community
  • 1
  • 1
Daniel Vassallo
  • 337,827
  • 72
  • 505
  • 443
4

its a perfectly valid path character, see page 27 of the spec http://www.ietf.org/rfc/rfc2396.txt

No reason not to use it

Andrew Bullock
  • 36,616
  • 34
  • 155
  • 231
1

I think differently of the others... I don't think it is a good practice to use it on the url.

IMHO it is way better if you version on the Content-Type Header.

As an example, if you are using application/xml:

Content-Type: application/v1.0+xml.

Using the Content-Type, it also indicates that the resource itself is versioned. While if you use it on the url it seems that you are versioning the service (which doesn't seem to be so), and if you are changing the service itself you will probably change the url, so you don't need the version number.

EDIT: You should also use it on the Accept Header, not only on the Content Type.

Diego Dias
  • 21,634
  • 6
  • 33
  • 36
  • 1
    Look more closely at the the question and the answers. Most of the answers are referring to the use of a period in the Url, nothing to do with versioning. I brought that up, but it was not the original question. – Darrel Miller Apr 20 '10 at 23:28
-2

I think it is a good idea. I've seen several rest services that do this.

Byron Whitlock
  • 52,691
  • 28
  • 123
  • 168