HTTP status code for "client software update required" - what to use?
Asked Answered
P

5

21

Which HTTP status code I need to return to indicate "client software update required"? For example, the server changed the format of the data it used to serve, and older clients won't be able to work with this, so the client must upgrade to use the new data.

I don't want to use 404 or 410, because I want to indicate it's still a valid path. 415? Not sure.

Phelan answered 22/4, 2012 at 16:58 Comment(5)
This is a good answer to a related question, which suggests how to do versioning, and which codes to use: #389669Befit
Arjun, thanks for the link - speaking of 3xx codes, they would be more apropriate maybe, but still none of them quite match the condition. In my case the resource have not moved (temporarily or not). The resource is there, but client should be updated. Still unclear about which code is appropriate for this.Phelan
A question then: How does the server know that the client needs to be updated?Befit
Ah! I see now from your comment on one of the 'answer's. The version number is in the URL. Isn't it clear then that: (1) since you're not returning a 2xx with data, and (2) the data is at another location (since URL will change), that 3xx is the only way to go?Befit
I guess, I'll use 418 as all other codes are confusing.Arrears
F
12

The majority of commenters are concerned that you're breaking old clients while using the same URI, which is a reasonable concern. That's why many APIs are versioned in the URIs themselves.

That said, why not just 400? The request came from an old client, so it's a bad request.

Fortunio answered 10/8, 2017 at 21:59 Comment(1)
Agree. A 400 response with detail message like {'code': 'UPGRADE_NEEDED', 'message': 'Please upgrade to version 2.0.'} will be better.Gwenette
M
1

why not just include the minimum supported client version as meta data in the api response? Then the client can check and prompt the user to upgrade as needed. No need to use a particular status code, just check the meta data on any response.

Masterly answered 4/10, 2018 at 10:34 Comment(0)
E
-2

I think the response code 409 is the best for this.

409 Conflict

The 409 (Conflict) status code indicates that the request could not be completed due to a conflict with the current state of the target resource. This code is used in situations where the user might be able to resolve the conflict and resubmit the request. The server SHOULD generate content that includes enough information for a user to recognize the source of the conflict.

Conflicts are most likely to occur in response to a PUT request. For example, if versioning were being used and the representation being PUT included changes to a resource that conflict with those made by an earlier (third-party) request, the origin server might use a 409 response to indicate that it can't complete the request. In this case, the response representation would likely contain information useful for merging the differences based on the revision history.

Epiphenomenon answered 20/9, 2022 at 23:40 Comment(0)
C
-3

If it's still a valid path, then your server should continue to support it, instead of indicating an error.

It seems a bit as if you are asking the wrong question :-)

Calfee answered 22/4, 2012 at 17:54 Comment(4)
The path is valid, meaning that it exists and still provides data. But if I keep supporting both versions, I will end up maintaining multiple versions of data (which is OK in the short run, but not OK in the long run). I want to tell the user that even though it's a valid path, he should upgrade his software to new version to take advantage of the latest new data I provide. Otherwise he will be stuck with old version not even aware it's old. He's going to think it's just never been updated.Phelan
Sorry, I don't see the difference. If you send a 2xx code, the users won't notice. If you send a 4xx code, the break the clients. I don't think there's anything in between. If you want to "deprecate" the old URIs, put something into the payload telling people they need to upgrade.Calfee
Julian, my question was more out of curiosity. I plan to have a data format change in a few weeks, which will require users to upgrade their software and would like to make it as smooth as I can to users. Most will upgrade and get new functionality with no issues. But there are always a few who keep using the old versions of the software. I am concerned about them. I don't want to return 404: it might be confusing. I thought this situation is not be very uncommon, but apparently there are no specific HTTP codes for this. For now, I guess I will use 415. I could also use some custom 6xx code.Phelan
antonio: 415 is for a different use case. 6xx would be invalid. If you want to mark the URIs as non-supported, the right way to do so is ti use 404 or 410.Calfee
S
-12

426 Upgrade Required

https://en.wikipedia.org/wiki/List_of_HTTP_status_codes

426 Upgrade Required The client should switch to a different protocol such as TLS/1.0, given in the Upgrade header field.

Schuler answered 31/3, 2015 at 8:18 Comment(1)
This status code specifically refers to the protocol in use, and not client software, so implementing this on a public API would be confusing. Even in a closed system someone might expect other functionality based on the status code.Viscacha

© 2022 - 2024 — McMap. All rights reserved.