encoding mobile-device versioning for REST Api server

Question

We have restful api over HTTP. Amongst other clients we have also mobile-device clients (e.g. iphone). The issue is that there are several iphone apps in different versions out there (1.0, 2.0). Because they are distributed we don't have control which app-version is calling us.

To identify the app-version on server-side I see following options:

1. device must append URL parameter (e.g. /foo?iphone-app-version=1.0) : A bit yucky, but good thing is that I can see it always on server-logs (URL is always logged)
2. we authenticate api-clients with HTTP digest. We could encode the app-version inside the username (e.g. iphone_1_0): Good thing it is logged in server logs, but only works for resources which are exposed as HTTP digest.
3. device must use custom HTTP-header, e.g. X-IPHONE-APP-VERSION: In my view the cleanest approach, but we don't log HTTP headers in server logs (for log-noise it is switched off). So later analyzation is not possible.

Do you have a preferred approach or any other alternatives?

EDIT: With above versioning I don't mean api-versioning/content-negotiation. It is the version of the mobile-device.

Answer 1

You can use the Accept-Header to allow a client to declare what capabilities it has by identifying what versions of media types it supports. e.g.

mobile app does:

GET /server/foo
Accept:  application/vnd.acme.fooappV1+xml

When you introduce new features that are not backward compatible you can tell the new updated clients to send,

GET /server/foo
Accept:  application/vnd.acme.fooappV2+xml

Then your server knows the capabilities of the client it is talking to. You could also get the new clients to do this:

GET /server/foo
Accept:  application/vnd.acme.fooappV1+xml, application/vnd.acme.fooappV2+xml

That way you can migrate your server resources over to the new format slowly. If the endpoints deliver application/vnd.acme.fooappV1+xml then the client will revert back to the old way. If the endpoints return application/vnd.acme.fooappV2+xml then the new code can take over.

Using this approach, no URIs need to be changed, so bookmarks and statistics remain valid. Migration to a new format can be done incrementally over time and support for old clients can be gradually phased out.

Answer 2

I decided for custom X-xxx-USER-AGENT one. Main reason to decide against more standard "User-Agent" is that is already "polluted" with http-client library or mobile-device information. A custom X-xxx-USER-AGENT is easier to parse for server and does not intervent http-library which often sets it and could override a custom entry.