undefined | Better HN

0 pointsnikcub15y ago0 comments

I don't like API version numbers in the URI.

It implies that a resource is different just because you are using a newer version of the API.

My own most recent implementations use Accept: and Content-Type to define version compatibility, which is what content negotiation is supposed to be about.

Versioning in the old web API sense meant changing the way the protocol works, and REST will always be REST and the resources will always be resources.

All that is likely to change between 'API versions' is formats, which you negotiate with headers, and adding new fields, which old clients can either ask not to get through content negotiation or can safely ignore.

0 comments

12 comments · 5 top-level

Groxx15y ago· 5 in thread

I can see it both ways.

APIv2 is not the same resource as APIv1, so why send it to the same location? Similarly, APIv1/user/1 may very well not contain the same information as APIv2/user/1, so are they really the same resource? They likely refer to the same semantic resource, but if user/1 != user/1, they're not the same from a data standpoint, which is what APIs are generally used for.

enduser15y ago

It is the same resource. User #1 is the resource. The URL refers to the user, or the user's account. Unless the user creates a new account for use with API v2, the URL should be the same. API v1 and v2 may represent the resource differently, but they are the same resource and should have the same URL.

The correct method for selecting a specific representation is to use the Accept header on the request. For example, if I were requesting somedomain.com/Groxx I could specify Accept: image/png if I wanted a picture of you, or Accept: text/x-vcard if I wanted your contact information.

coderdude15y ago

I believe you are incorrect. From the 1.1 spec:

"The Accept request-header can be used to specify certain media types which are acceptable for the response."

Similar to how when you access some linked data URLs you can specify rdf/xml or rdf/n3 in the Accept header to receive the same data in a specific format.

It's not used to specify whether you want a picture of someone or their contact information all from the same URL.

1 more reply

nikcubOP15y ago

If version 1 of a resource is not a subset of version 2 of a resource, and they are not accessing the same record, then they should be separate resources

what 'API' is signaling is what the client is capable of understanding, which is what content negotiation headers are for

I think of it no different to the same resources for web browser consumption (for humans) - I don't place new designs of a website into /design1/ /design2/ etc.

jerf15y ago

Bear in mind the more things like "Well, you just have to properly use the content negotiation headers" you add to your API, the more the "simplicity" argument of REST goes out the window. I'm not sure I've ever seen really correct use of the content-negotiation headers and claiming it's a solution is dubious... sort of like how I'm still waiting to see proper use of XML Namespaces in the wild. They seem relatively simple to me but the evidence suggests strongly otherwise.

That doesn't make REST "bad", but I think it does start to make the quasi-religious aspect of it less obviously correct.

2 more replies

nikcubOP15y ago

if you don't want to use content negotiation, then stuff it into query parameters - that is what most API's do (and most that support full content negotiation do anyway)

eg.?v=1&format=xml

but interesting to note is that why is encoding easy to do as part of content negotiation, yet everything else is hard? you never see ?e=UTF-8 or &c=gzip

2 more replies

stanleydrew15y ago· 1 in thread

I completely agree from a pure REST perspective, but if you want developers to be able to quickly get up to speed with your API, requiring them to know the finer points of HTTP and how to manipulate headers within their clients is asking a lot.

mark_story15y ago

Is it though? They are developers, developing applications for the web. I don't think its a huge barrier to expect people to learn the basic protocols, and tools like curl reasonably well.

antihero15y ago· 1 in thread

How do you do authentication?

danssig15y ago

With the methods provided via HTTP.

jbert15y ago

Do you have full control over the clients which make requests (e.g. it's only AJAX or 3rd party clients written to your api spec - i.e. not browsers making raw requests against some of your urls?)

I backed away from using content-negotiation for an API, part of which would have served data and part content.

e.g. to access file metadata, get /path/to/file with Accept: api/v1 and do a 'normal' GET to get the file contents.

I came across some suggestions that some browsers (recent IE I think, unsure) which suggested that cacheing was broken wrt Accept header - which made me worry that people hitting accessing the resource might get the wrong version.

I don't know if your api is vulnerable to this, if you've come across the problem or have any deployment wisdom to share.

sunir15y ago

The problem is the data model may change between versions so the URL hierarchy will change. Or instance you may have split customer and staff into separate concepts but later decide your service is better imagined as a network and thus only have users.

j / k navigate · click thread line to collapse

0 comments

12 comments · 5 top-level

Groxx15y ago· 5 in thread

I can see it both ways.

enduser15y ago

coderdude15y ago

I believe you are incorrect. From the 1.1 spec:

"The Accept request-header can be used to specify certain media types which are acceptable for the response."

Similar to how when you access some linked data URLs you can specify rdf/xml or rdf/n3 in the Accept header to receive the same data in a specific format.

It's not used to specify whether you want a picture of someone or their contact information all from the same URL.

1 more reply

nikcubOP15y ago

If version 1 of a resource is not a subset of version 2 of a resource, and they are not accessing the same record, then they should be separate resources

what 'API' is signaling is what the client is capable of understanding, which is what content negotiation headers are for

I think of it no different to the same resources for web browser consumption (for humans) - I don't place new designs of a website into /design1/ /design2/ etc.

jerf15y ago

That doesn't make REST "bad", but I think it does start to make the quasi-religious aspect of it less obviously correct.

2 more replies

nikcubOP15y ago

if you don't want to use content negotiation, then stuff it into query parameters - that is what most API's do (and most that support full content negotiation do anyway)

eg.?v=1&format=xml

but interesting to note is that why is encoding easy to do as part of content negotiation, yet everything else is hard? you never see ?e=UTF-8 or &c=gzip

2 more replies

stanleydrew15y ago· 1 in thread

mark_story15y ago

Is it though? They are developers, developing applications for the web. I don't think its a huge barrier to expect people to learn the basic protocols, and tools like curl reasonably well.

antihero15y ago· 1 in thread

How do you do authentication?

danssig15y ago

With the methods provided via HTTP.

jbert15y ago

Do you have full control over the clients which make requests (e.g. it's only AJAX or 3rd party clients written to your api spec - i.e. not browsers making raw requests against some of your urls?)

I backed away from using content-negotiation for an API, part of which would have served data and part content.

e.g. to access file metadata, get /path/to/file with Accept: api/v1 and do a 'normal' GET to get the file contents.

I don't know if your api is vulnerable to this, if you've come across the problem or have any deployment wisdom to share.

sunir15y ago

j / k navigate · click thread line to collapse