- Hands-On RESTful Web Services with TypeScript 3
- Biharck Muniz Araújo
- 553字
- 2021-07-02 12:19:22
Versioning
As APIs are being developed, gathering more business rules for their context on a day-to-day basis, generating tech debits and maturing, there often comes a point where teams need to release breaking functionality. It is also a challenge to keep their existing consumers working perfectly. One way to keep them working is by versioning APIs.
Breaking changes can get messy. When something changes abruptly, it often generates issues for consumers, as this usually isn't planned and directly affects the ability to deliver new business experiences.
There is a variant that says that APIs should be versionless. This means that building APIs that won't change their contract forces every change to be viewed through the lens of backward compatibility. This drives us to create better API interfaces, not only to solve any current issues, but to allow us to build APIs based on foundational capabilities or business capabilities themselves. Here are a few tips that should help you out:
- Put yourself in the consumer's shoes: When it comes to product perspective, it is suggested that you think from the consumer's point of view when building APIs. Most breaking changes happen because developers build APIs without considering the consumers, which means that they are building something for themselves and not for the real users' needs.
- Contract-first design: The API interface has to be treated as a formal contract, which is harder to change and more important than the coding behind it. The key to API design success is understanding the consumer's needs and the business associated with it to create a reliable contract. This is essentially a good, productive conversation between the consumers and the producers.
- Requires tolerant readers: It is quite common to add new fields to a contract with time. Based on what we have learned so far, this could generate a breaking change. This sometimes occurs because, unfortunately, many consumers utilize a deserializer strategy, which is strict by default. This means that, in general, the plugin that's used to deserialize throws exceptions on fields that have never been seen before. It is not recommended to version APIs, but only because you need to add a new optional field to the contract. However, in the same way, we don't want to break changes on the client side. Some good advice is documenting any changes, stating that new fields might be added so that the consumers aren't surprised by any new changes.
- Add an object wrapper: This sounds obvious, but when teams release APIs without object wrappers, the APIs turn on hard APIs, which means that they are near impossible to evolve without having to make breaking changes. For instance, let's say your team has delivered an API based on JSON that returns a raw JSON array. So far, so good. However, as they continue, they find out that they have to deal with paging, or have to internationalize the service or any other context change. There is no way of making changes without breaking something because the return is based on raw JSON.
- Always plan to version: Don't think you have built the best turbo API in the world ever. APIs are built with a final date, even though you don't know it yet. It's always a good plan to build APIs while taking versioning into consideration.
- 郎景和院士“關(guān)愛(ài)女性健康”系列:婦科腫瘤的故事
- 中華口腔醫(yī)學(xué)會(huì)團(tuán)體標(biāo)準(zhǔn)(2017—2022年)
- 乳腺癌綜合診治規(guī)范化手冊(cè)
- 血液病臨床診療精要
- 災(zāi)難醫(yī)學(xué):管理篇
- 朱德生皮膚病學(xué)(第5版)
- 活血化瘀方藥臨床使用指南
- 長(zhǎng)腿叔叔:孩子有話說(shuō)
- 身體關(guān)節(jié)功能篩查及糾正
- 帕金森病中西醫(yī)結(jié)合診療與康復(fù)
- 龍層花健脊防癌方案
- 深呼吸:菠蘿解密肺癌
- 走出抑郁與焦慮:中西醫(yī)視角下的心身同治
- 實(shí)用透析手冊(cè)(第3版)
- 家庭護(hù)理指導(dǎo):腫瘤病人家庭護(hù)理