14

We're running an API with quite a few people using it. Due to some legacy clumsiness on my part, one of the endpoints is returning the wrong content-type header, js when it should be json. My question is, if we fix this by swapping to return the correct value, how badly could it mess things up for our existing customers? Or to put it another way, would you expect many different HTTP client libraries to throw fatal errors when seeing such a change?

We're trying to decide if this is a change which we can just go ahead and make without sweating it too much, or we should carefully email all users and announce a multi-year deprecation period ...or something in between.

It probably depends a bit on what kind of different HTTP clients are in use, so I took a look at user agents. Answer: a lot of different ones! Here's some of the top ones:

"okhttp/3.2.0", "python-requests/2.10.0", "Ruby", "python-requests/2.7.0", "Mozilla/5.0", "Java/1.8.0_91", "python-requests/2.4.3", "okhttp/3.3.0", "Lucee", "Dalvik/2.1.0", "Google-HTTP-Java-Client/1.21.0", "PHP_appname", "NativeHost", "Java/1.7.0_67", "Apache-HttpClient/UNAVAILABLE", "Dalvik/1.6.0", "Web-sniffer/1.1.0", "unirest-objc/1.1"

Various different mobile and server side language libraries. Mostly not browsers running javascript, but some of those too.

Most people don't seem to notice that the content-type is wrong, but every now and then a new support request pops up complaining about this issue, so we'd like to fix it.

Improve this question
4
  • 4
    I would assume that clients that work correctly with an incorrect content-type header won't stop working once you set the correct one, but you know what they say about assumptions. So test, communicate your changes to your user base in advance and/or built in some additional logic that if a certain client does break, you can detect that particular client and keep returning the incorrect content-type header (or do the reverse, return the correct one for those clients that generate support tickets and keep everything the same for current users/user-agents).
    – HBruijn
    Aug 2, 2016 at 20:13
  • 5
    mandatory xkcd: xkcd.com/1172
    – njzk2
    Aug 3, 2016 at 19:46
  • Aren't you versioning your API?
    – Michael Hampton
    Aug 3, 2016 at 20:19
  • We only have a major version number for the whole API which we would only look to bump in a few years time when we make some fairly major restructurings. At that point we'd fix this issue of course, but... feels like we may never do this. It's one of those version numbers.
    – Harry Wood
    Aug 4, 2016 at 13:54

5 Answers 5

Reset to default
30

how badly could it mess things up for our existing customers?

It could completely sink their battleships if they've written code that relies on this Content-Type being incorrect.

I would not expect the libraries to throw errors, but I expect that in some cases strict libraries have had their behavior overridden to handle the incorrect MIME type.

If your API has a version/revision value in a request field somewhere, raise it, and in the new version return the correct type but continue to return the incorrect type in the older versions. If you don't have such a request field, now is a good time to add one.

Improve this answer
14
  • 6
    +1 already for a good hyperbole
    – HBruijn
    Aug 2, 2016 at 20:15
  • 4
    Often you don't have a choice. Customers given an "update or leave" ultimatum may decide on the latter, good in principle, bad in practice. The old version can be retired over time.
    – alzee
    Aug 3, 2016 at 3:55
  • 3
    +1 vor versioning the requests, though you may want to check out en.wikipedia.org/wiki/Software_versioning for further information.
    – SBoss
    Aug 3, 2016 at 7:28
  • 7
    @WinstonEwert: Of course it is worthwhile. People specify which API version they want to use, then their program doesn't spontaneously combust in the time between you updating your API and them updating their program. If you don't do this, you automatically break every current and historical release of your clients' code when you change your interface. And that's a dreadful way to run a service.
    – Lightness Races in Orbit
    Aug 3, 2016 at 9:51
  • 1
    This seems like a very good point by way: "I expect that in some cases strict libraries have had their behavior overridden to handle the incorrect mime-type" My hunch (as an answer to the whole question) is that the vast majority of client libraries will be fine with this, but this is a concern. Some customers may have pro-actively worked around this, and swapping will then break it for them. I wonder how much of that has happened.
    – Harry Wood
    Aug 3, 2016 at 11:45
11

Would you expect many different HTTP client libraries to throw fatal errors when seeing such a change?

No. Every HTTP client library I'm familiar with will ignore the content-type header unless the programmer specifically reads that header and does something with it. I can imagine a library where the content-type: application/json automatically causes a json parser to get involved but I don't know of any case where that actually happens.

Most people don't seem to notice that the content-type is wrong, but every now and then a new support request pops up complaining about this issue, so we'd like to fix it.

How did they notice the incorrect header? It might be worth looking at that, because if the incorrect header was actually causing them problems they clearly weren't just ignoring it, and they might have problems if it is fixed.

Improve this answer
2
6

Too hard to tell without getting sign-off from all of your clients. I would suggest taking one of the following two approaches to upgrade your API to v.Next.

  1. Extend existing API. Add a query string or some other variable to your API that signifies to use v.Next. For all requests using that variable, use the updated content-type.
  2. Run a Staging or Pre-Production instance of your API in parallel with your current API. It should be nearly identical to production. Even using the same back-end. Although this one will have the proposed changes for v.Next.

In either scenario, communicate to your clients the changes you'd like to make and the target cutover date/time. Encourage them to test well before the target date to ensure there is no service disruption.

Ensure you have a dedicated page detailing the changes made to v.Next. This should be included in the communications sent out to your clients. If you've discussed any fixes with existing clients, include those on this page.

Finally, tread the line between over-communicating with your customers and spamming them. These notifications can be easily overlooked as more immediate/urgent priorities come up.

FWIW, if things are currently working I wouldn't worry too much about it. If for example you find that this causes a significant security vulnerability then that would be a great reason to push out this change. Otherwise I'd wait for something more pressing to include this change with.

Improve this answer
1
  • Thanks. It's not the answer I wanted to hear, but maybe you're right. We just need to introduce the change very cautiously. Is it "Too hard to tell" though? I guess I was hoping some folks would have experience of the likely impact of this particular kind of content-type header change (leaving aside the more generic points about versioning cautiously)
    – Harry Wood
    Aug 3, 2016 at 11:49
5

Here's an example of a library (well, single command) that this would break:

The cmdlet Invoke-RestMethod acts differently with JSON. If the result of the request is JSON, XML, or ATOM/RSS (and I think it's based on the header), it parses/deserializes it and returns native objects, otherwise it returns the raw data.

So the existing code would be written to deal with a string (perhaps by passing it to ConvertFrom-Json), and would all of a sudden start failing.

Improve this answer
1
-2

I have noticed two consequences:

  1. Some client libraries will not process the response properly. For example, the response returns a string instead of json or an array.
  2. Compression is not always applied.
Improve this answer
1
  • Surely it's the one sending the data, not the one receiving it, which applies compression?
    – TRiG
    Aug 3, 2016 at 13:36

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .