Standard Practices For Communicating API Response Changes To Clients

[API Dev]

Hi,

My question is - What are the standard practices followed by companies to communicate changes in the API responses to clients? 

We have enterprise rest api's that are exposed to our application users. One of the third party library upgrades unknowingly caused minor changes in the api response (json). This broke our client code. To fix it, we plan to make very minor refactoring's (changing a json attribute to its plural form) that would make the responses consistent across all exposed api's. I wanted to understand what are the best possible ways to do that? I do not think we need to do version the api here. How do enterprises generally share such updates to the api responses with their clients?

Thanks!

[Jørn Wildt]

Simple answer: don't do it :-) NEVER change names, change types or remove properties.

If a published vocabulary (set of public properties) has spelling issues then add the new, correct, spelling and support the old ones. You don't "refactor" published APIs, you only add new ones.

We have had the same issue. A string property "Keyword" went from a single keyword to multiple keywords. So we added a new array-of-strings property "Keywords" and copied the first of them into the legacy "Keyword" property.

/Jørn

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+unsubscribe@googlegroups.com.
Visit this group at https://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[API Dev]

Thanks for the response. 

I understand that adding new and supporting old ones would not break client code. One follow up question though - Won't you have to communicate to the clients still that there is duplicate information which should be ignored (at least for new clients that start using the api after this change and assuming that the information is implicitly ignored by the old clients)?

In the "keyword" and "keywords" example, we will have to let clients know that the keywords array is returned twice in the api response and the list is the same in both. How do you handle this confusion?

To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.

[Peter Williams]

Just document the new and old properties, and their relationship, in the normal API documentation. If client developers are confused they will consult the documentation and be enlightened. 

To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+unsubscribe@googlegroups.com.

[API Dev]

Ok. Yes, the documentation could make it clear.

One downside I realized while analyzing this approach further is that the amount of data returned by the server now would be double and that would have an impact on the web api contracts that our api adhere's to. Any workarounds to this?

Thanks.

[sune jakobsson]

As Jørn says, don't do it. Consider supporting both versions for a while, and tell your clients to update, and then at som point let the old version return 301 Moved Permanently.

Sune

To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+unsubscribe@googlegroups.com.

[API Dev]

then at som point let the old version return 301 Moved Permanently.

I didn't follow when and how would you return 301. Did you mean introducing a new http header parameter for the server to detect that the plural form of the response needs to be given and the requests that do not have this new header parameter would support both the formats. At some point the header parameter would be obsolete and the server would return just the new format? 

Thanks.

[Peter Williams]

I wouldn't worry much about the amount of data. The actual data increase is likely to be rather small, in practice. Also, make sure you support compression transfer encoding [1]. Most web formats compress *very* well. 

Peter

barelyenough.org

[1]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Transfer-Encoding

To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+unsubscribe@googlegroups.com.