2

I am re-designing my previous century app (which works very well, mind you), and the chance to start fresh has me investigating several aspects. This question is re. versioning.

The app is really collection of data apps that deliver resources--query is http and response is JSON. Now I want to change one of the responses. After reading around, I have decided to not implement versioning via the URI or query_string. Instead, as advised in Best practices for API versioning?, especially the second answer (is there not a way on Stackoverflow to link to a specific answer?), I am using headers. However, instead of using Accept: application/vnd.company.myapp.customer-v3+json I am using

Accept: application/json
X-Requested-With:   XMLHttpRequest
X-Version:  2

On the server side I am able to check the value for X-Version. If it doesn't exist, the query uses the latest API. It X-Version does exist, then the request version is used. The above works fine.

My question is -- any gotchas I should be aware of? Esp. since I pulled this X-Version out of my butt. As far as I know, it is not an officially sanctioned header.

Update: Drats! even before posting this I read Custom HTTP headers : naming conventions, and it seems I should not use the X- prefix. However, then there is a possibility of my home-grown header conflicting with an existing standard unless I first do due-diligence. Thoughts?

Improve this question
3
  • Why have you decided not to use media type versioning? What "scope" does your X-Version (or MyCompany-Version) pertain to? Commented Jun 24, 2013 at 19:33
  • honestly, I didn't use media type versioning because I don't know what it is and why I should use it. I can't answer the second question because I don't understand the meaning of "scope" in the context of the question. Perhaps you mean what does X-Version refer to. Specifically, it refers to the resource being requested. In other words, the query is saying, "get me the resource at the end of this URI using the API version 2 which is applicable only to this resource." In other words, other resources can continue use their own respective API versions. Commented Jun 24, 2013 at 19:40
  • it is so meaningless to close a 10 years old question that already has a number of responses. Contrary to what the esteemed editor thinks, I am not asking for opinions. I am asking for the right way to program something Commented Dec 22, 2023 at 13:16

2 Answers 2

Reset to default
2

I prefer the custom header especially with the current trend of reverse proxy with microservices and traffic management among application versions.

X-App: <app_name>:<app_version>
Improve this answer
Sign up to request clarification or add additional context in comments.

Comments

0

There is a lot of debate around the "right" way to do this. For some high level thoughts, check out mnot's: WEB API VERSIONING SMACKDOWN

For a very in-depth discussion, check out this post to API-Craft: https://groups.google.com/forum/#!topic/api-craft/E8MBkzirdcw

Personally, I favor a combination of media type versioning, and link relation versioning, to accomplish this.

Improve this answer

3 Comments

Great reads, those links you provided. However, I still need some clarity. Example: I have a URI that returns JSON that is already being used by an iOS app. Now I want to change the structure of the returned JSON, but I don't want the existing app (installed on lord knows how many devices) to break. Using X-Version works. The URI doesn't change, but different versions of apps can get the correct data. Also, since versioning is per URI, an app can use URIs of different versions. How does media-type and link-relation versioning fit in such a scenario?
Are you trying to make a breaking change to the format? Or an addition?
In this case the change may not break anything, but that is my guess. Only the app developer would know for sure. I do intend to follow semantic versioning, but I have to make a sustainable API design principle. I can't possibly guess whether my changes will break other people's apps. What I can do is provide some kind of versioning so they can choose to use whichever version they desire.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.