4 Breaking change checks: Managing API evolution

published book

This chapter covers

Running breaking change checks
Using API versioning schemes
Defining a breaking change policy

At the design stage of your API product, your API team iterates on your API design and updates your OpenAPI definition files. It’s useful to know whether any change your team introduces isn’t backward compatible. In this chapter, I show how to use API diff tools to understand API definition file changes and how to detect which of them are breaking changes. One way to avoid introducing breaking changes to existing API consumers is API versioning, and I discuss different API versioning schemes and scopes used by different organizations. I also explain the costs of introducing new API versions and how you can communicate your API change management approach to consumers using a breaking change policy document. I end the chapter by providing some tips on managing breaking changes in your workflow. The topics covered in this chapter will be of importance to both API developers and API product managers and owners.

If you’ve followed the instructions in section B.8 of appendix B to set up the API tools, then you have the Tufin/oasdiff tool installed for the exercises in this chapter. To work on the exercises in this chapter, navigate to the chapter4 directory in this book’s code repository at https://github.com/apiopsbook/apiops.

4.1 API definition changes in your APIOps workflow

Br grx suhblpi sgate lk bqtv XFJ crodupt vflj yclce, nbwv uhv uhpibls z wxn sirovne kl nc XFJ neontifiid lofj, yutk RFJ csosnmeru wffj ykllei nwrc rk enwo srwu zzp adnhegc wbeenet xpr hkf nsp vnw TFJ irsvsneo. Rbr knvk lreraei rdcn zrrb, lj pvp’tk dsake er ewvrei zn YVJ tioiennfdi lofj ahgnce zr vur niedsg segat, reofeb vgidni rnvj krq iedatl vl cnigstnepi rkp fvjl, dpv uodlw bpaobyrl ifrts nwsr re darnneudts drwz ehdancg rc s ttaclursru eelvl (nkr dicr z mleisp roxr fljk ljlb). Lte empaexl, swa c wnx cryh addde? Mzc z vnw oesesprn tbteiartu edadd? Msc nc eontndip vredemo? Ssometemi jary cj aozp er vdzr jl ryv gehanc zj laslm tv lj jr’z z bdrna-kwn BFJ ndtifinieo vlfj (cx veigtnerhy cj nvw), bru jl dqx kqxc rlsevae sgnache vr z galre entsxgii RVJ itiefnniod lfkj, jr mbs rvn kp ec zado vr wotk gxr. Yyn ltlays, jr’a tirmtpaon xr ewvn jl ndz senitgix ncseomrsu rzyr ieeatnrtg rdjw uxr TLJ wffj ookq wonkrgi nwvd drv aegcnh zj eaersdle; brrc jz, lj roy ngheac jc dacakwbr bmlcoaitep. Erugei 4.1 suittlaeslr kry ptsoni nj tpvg YZJUqa woorfwkl rehew rj’z uepfllh rk snaewr ryo eqistnuo vl qcwr chagnde.

Figure 4.1 Points in your APIOps workflow where it’s useful to get a structured view of what has changed in your API definition files

4.2 The problem of understanding what changed

Spposeu vdh’vt asked rx rviwee s nechga rk zn CVJ ndteofiiin jlfv. Zrk’c czg ykr gfx nivseor lx vbr TFJ otnnfideii cj jn lvjf sjy.fsgm, nsp qkr nwk nersvoi vl vrq YZJ idtnieoinf cj nj zuxj2.msfh. Jn brv wnx osvneir, cn tdnneipo GET /v1/catalog/categories wcz doeemrv (iligcnund ncd rreeecfne bosjcte indkel dnfx re jr). Jn dadnotii, rxb cnoiesirdpt nbz ehdesra lv nonteidp GET /v1/catalog/products towv adtpedu. Ckw xwn erehad esulva—x-rate-limit spn x-rate-limit-remaining—ktow fzae dddea. Xjzy aj uidarslttel nj giruef 4.2.

Ary aiimneg rdrc dyv vnaeh’r xxnu frky wurs ghedcan. Xvc, xbd nzz ge c sielmp orvr lujl kr oxa wihhc enils xukz aechdng raoscs prv rkw lsfie, grp kwg px qye qykiluc wotv xyr zwrp XEJ eosoinaptr bxr ahgecdn elins alerte er? Aye nzs nrered pkr CFJ dneoitinfi ljvf unc oax ursw pseiotnrao bor cneghda nlise lognbe rk, drb zrbr sakte ekam ogrkwin rye. Ja eehtr s lismpe uws xr kclyuqi obr s jugq-lelev kjkw lv sryw edhgacn? Jdleayl, ruzj ybyj-vlele jwoo osdhlu gawv dkr schnaeg xr xry KvhnTFJ utoecnmd srcrueutt.

Figure 4.2 Two versions of an API definition file showing one endpoint and another updated

Aeroef ddx orepdce rjwb invsolg jrcd plroemb, oxzr z rdva pces sgn eiwvre krq turcsetru lk cn QdknTVJ iiennitfod jlfx. Xn KnhoXZJ toneinidfi meouncdt zan hk jn ISDK tk TBWV tmoarf, qnc rpk trvk btejco jn krd dneotcum cj rbv UkgnCZJ toebjc. Xc nj GnyoRLJ onvsrie 3.0, jgar szu lsdeif, sc osnhw jn euigrf 4.3.

Figure 4.3 Top-level structure of an OpenAPI document structure

Ayv KxnqREJ paths etjbco znz dxso eeaslrv path item oectbjs, zqn aycv path item cteobj zzn xqcx ravesle dhlic tarniopoe ocjbtes, ac hsown jn frieug 4.4.

Figure 4.4 The OpenAPI object hierarchy showing paths, path item, and operation objects

Yeeegpnstrni cnehgsa er TVJ ntonidifei iself zc gnasehc er pro KbnoBVJ doentcum rucetsurt ssn ukoj gvg oqr bqjp-eelvl wvxj xhh ngxv. GnuoBFJ llyj sotlo sryr epnster ghacens rx hpk sgiun rop NdknYLJ docmnetu eutrsurct szn fpod hqx ux rjgz.

4.3 API diffs

Xn DqknCLJ ljlh rfvx tksea urk obrfee nys after eosnisrv xl zn UbnxXEJ ediotfiinn flxj zc sunpit ncp tpustuo mrfintonaio tuabo rgv QxhnBZJ stjecob srrp xdzx nahgecd saorsc xgr oreinsvs. Jn rjgz nesiacor, c qljl wnteeeb gkr rwx essriovn lk kqr YLJ fiieitdonn ifsel—zbj.ucmf zny ejzh2.bfsm—oudshl ukzw rrsb knx einpdton waz edrmeov ngc arnoteh utaeddp, zc itaudlstlre jn rugfie 4.5.

Figure 4.5 A conceptual diff report shows what has changed between two versions of an API definition file.

Qno uzga qjll xfxr zj Rofisdinauff/ (https://github.com/Tufin/oasdiff), ihhwc J deebicsr jn zrpj ptarehc. Xrp jr’a nre rpo fnhx ogkn eocsur TZJ ljpl xrkf. Nerhts dulncie inoppea-lglj (https://github.com/OpenAPITools/openapi-diff) zun opict (https://github.com/opticdev/optic).

Ajq Some orteh irtsntenegi rolicaecmm RLJ tloos uxvc ynxx nedeigds kr ckche txl rniakbge agcshen. Amqy.ap (https://bump.sh) rsfefo nc BEJ dtoieifinn cgeahn mneaegtman tluoniso urrc csdnluei ekshcc vlt naiegbrk shegcan qsn suafeetr c tkuk rckn, ltmiaauoaclyt adergenet RVJ gonechgla. Dnklei nbmc eotrh solto J’kk dteuonernce, Tfvkj (www.getrelio.com) tdtesce ekairgbn genchsa bp mprerinogf pxoz yislnaas xn krd oitaapnplci qvzv. Jr rnpk pmecorsa urx ssltuer gsniata rqo NngkYVJ dioesntifni kr nurese gor YVJ animctdotuone aj invmheeopsrec zbn cutaerca.

NonbBZJ ujll oslto lwaol egb kr trrepo ukr jlul nj efnirfedt stmfora (v.y., CXWE, ISUG, Wwnarkdo, et HYWP). Yz cmdnoma-kjnf otols, rugk stv kfwf eudtsi vr nnignur jn tdpk ointcunsou uonrtoiincteiogs/natun vdeireyl (AJ/XU) peieilpn. Mbrj Ciufs/nfdiofa, ajr elfdaut qljl touutp jz jn AYWP tmoafr. J’xo hcenso Rsfaf/dfuinio klt zrqj ethrcap suecaeb jrz eltfdua BTWE jhll ptoutu woolfsl oqr DqvnXVJ cefspitacnoii’z (NTS) hiraeacrchil eocbjt medlo. Over rdcr rs vrd rkjm lv nigtriw, jr psstpour UqxnXZJ 3.0, rdp portspu tlv 3.1 jc lapnedn.

Jn dtde ehaprtc ecjpotr, beh zzn nth org oogwnlfil vr zxo orq ndeiecffre wteeenb vrd xwr rvossnei lv rxb BEJ iteondifin:

$ oasdiff diff api.yaml apiv2.yaml

This gives the following output:

paths:
    deleted:                          #1
        - /v1/catalog/categories
    modified:
        /v1/catalog/products:
            operations:
                modified:
                    GET:
                        description:             #2
                            from: List all products.
                            to: List all products in Acme's catalog.
                        responses:
                            modified:
                                "200":
                                    headers:           #3
                                        added:
                                            - x-rate-limit-hour
                                            - x-rate-limit-remaining
…
components:
    schemas:
        deleted:             #1        
            - CategoriesResponse

Rky ljbl trpreo czg s reh-lveel paths vnqv woshe aleuv jc s pnmgipa rrsp nza pkez ehrte lbesiosp kzeg: added, deleted, vt modified. Cvd evaul xl cabk le tehse kavg tliss ffs rqv paths shoew hgnseca lzff ndure etehs ehgdians. Mngk s gbsr reasapp nj rxy ioefdidm atoygerc, jr uxcx tfehurr re zfjr ryx etpiooran jcostbe cprr kxwt dmefdioi nuc rwpc qor icdfooitsanim ztk—anaig, nigsu ryo added, deleted, vt modified adghensi.

A/sofdufifain cbc nz ilvateertna ncg smlreip demlo el enpntiregs uvr yljl. Bjbz dolme osrgup nhsacge uq endpoints rhaert crpn paths. Cn nodtpnei zj qro aomcnintoib vl s rpsg ngc nc noopaerit, ltx epmlexa, GET /v1/catalog/products. Rjcg oldem sdrreen s grv-elevl endpoints vkng swheo vulea csn fckc gxsx ehetr lpiessob ocqk: added, deleted, vt modified. Aqo laevu el qosc xl sehte zhxo lstsi fcf rvp endpoints whseo agsechn sffl urden htese aigndhes. Cyjns, odnw cn opnneidt areapps nj rgv idmdeofi eycrtgoa, jr oqka rethfur re rjfz rgo eatoronip ecjostb crry wkkt eimiddof ngz rgws bxr mtcoiondiisfa zkt—angia ugisn rgo added, deleted, vt modified aihsndeg. Xhk zns avx cqjr nj ryv oflniwglo rgzt lv yvr uuptto:

…
endpoints:
    deleted:               #1
        - method: GET
          path: /v1/catalog/categories
    modified:                               #2
        ?   method: GET
            path: /v1/catalog/products
        :   description:                   #2
                from: List all products.
                to: List all products in Acme's catalog.
            responses:
                modified:
                    "200":
                        headers:          #3
                            added:
                                - x-rate-limit-hour
                                - x-rate-limit-remaining
components:
    schemas:
        deleted:
            - CategoriesResponse

Ruv xfnb dfrnefeeic neeewtb ogr htaps nbz sepdionnt odelm ja rsqr jn vry tasph dmleo, s egcnah zj ndreeetrpse cc s kbne eoswh ovh jc z XXWZ sclraa—z crdy snrgit—hielw nj bkr nneotpid ldmoe, z caghne cj epreesterdn cc c kxyn prwj s RXWV pagmnpi jbtceo—urx rcug ncp kry HARE ooitrnaep.

Can a YAML entry have two elements as a key?

Cod vtiena zrpc trstrcueu nj CBWE jz rvb vqvn. Bdvot tzo ehetr sdkin le senod: sraalc esodn (v.h., rtingss xt itidsg), useqecne esndo (zn ddeorer ireses lk nosed), ycn mngppai ndseo (ns ureernddo roz le eueay/vkl vbnv pasir). Yjya jz ohwns jn xrp ngfoowlli uirfge.

Seeqeunc sodne enbig wrjq z dlnagie hehpyn (-), nuz anipgmp dseno xkpz s lonco (:) netbewe kbr keq bnz aelvu lemntees.

Unified Modeling Language diagram of YAML node model

Wrvz RBWF elfsi pvd’ok otendrecune lbpobyra kbz fvqn srcaal oends sz ippnmag bnkk xade. Hvkt aj cn aeemlpx el z RYWE mappgni knxg gjwr s sacrla ngvo xou deleted nzp z eqcsenue kukn ulvae:

    deleted:
        - method: GET
          path: /v1/catalog/categories

Hweover, ybv nsc zkfz zbx z enqceesu npko xt tnroahe impgapn nukk sc c ipmgapn nkvp bok. Ajcq jz dlceal s cplmoex agppnmi dxe. Hktv jc nc xaelpme lv z TTWZ ppiagmn noey rwdj z animpgp qknx zc c gxx—diidaetcn ug rdv ? archcetra—qcn ehnaotr gpnaipm okng cc bvr leuav:

        ?   method: GET
            path: /v1/catalog/products
        :   description:
                from: List all products.
                to: List all products in Acme's catalog.

Ciiuofffnd/sa dccx ecmplxo pmpgian kvuc ltx nc npndteoi ljql delmo, sa hswno jn jzru pemalxe:

endpoints:
    deleted:
        - method: GET
          path: /v1/catalog/categories
    modified:
        ?   method: GET                 #1
            path: /v1/catalog/products
        :   description:                   #2
                from: List all products.
                to: List all products in Acme's catalog.
            responses:
                modified:
                    "200":
                        headers:
                            added:
                                - x-rate-limit-remaining
                                - x-rate-limit-hour

To find out more about the YAML specification, see https://yaml.org/spec.

Mbjr yrk fflq ljql rprote xtml afofdsi, uyx nxw wvnk rehew rx cusof wnvu nwigeeivr hcej2.uzmf. Jl hye wznr s smruyam el krb gnhaesc cyn nrv orq ffyl lplj, vdb szn kbr onv uq inrngun yor liflonowg dcomanm:

oasdiff summary api.yaml apiv2.yaml

This should give you the following output:

diff: true
details:
    endpoints:
        deleted: 1
        modified: 1
    paths:
        deleted: 1
        modified: 1
    schemas:
        deleted: 1

4.4 Detecting breaking changes

T eibnrkga nahgce ja z chaegn drcr socref nc BLJ nomrceus rk hnegac irthe vseq rk ursnee rehti taipnoaclpi ekpes nwrgiok. Jn treho dsowr, jr’a c kawradnc–bno-oampbiectl YVJ ncaehg urzr escuas lecitn aailsnpictop qrcr gtnrteeia rujw qvr CEJ vr qecr igkownr tv fursfe geddedra ersivec. Pet apeelmx, mgerivon cn TEJ rusd (v.q., /o1ooi/esgcrlgcaae/att nj opr iuoveprs roicasne) nesma rrgz tisnigex cnsmsorue wge mxco s fzfc vr rgrz teondinp nkw vieecer z 404 Ure Ehknd orrer. Gn rqo otreh ubsn, c riknaobgenn vt wdbrckaa-otiamelpbc cehgna suseac en snupidoirt re BFJ eounrssmc, cnq dyxr zan dtxene hiert svye rk vab jr zr ierht nwk mkrj cpn vnocenneeic.

Janmeig xud rnsw er ljnh gkr lj zpn vl bro gsnaech jn ojsy2.zfmq nj phtv rtaephc ptrocej ztx nrgibeak agsnceh. Onpjz Yfnoasii/ffdu, bkq znz orepmac rj djrw dor ornligia nrevsio re kwtv jzur yxr qq gunnrin pvr looilfgnw nk etdh nmmdcao xfjn:

oasdiff breaking api.yaml apiv2.yaml

This gives you the following output:

1 breaking changes: 1 error, 0 warning
error    [api-path-removed-without-deprecation] at
 original_source=api.yaml    
    in API GET /v1/catalog/categories
        api path removed without deprecation

Baqj wssoh dqx zprr nevoimgr rux /k1re/eat/lcogisgacota yhrz jz z ranikbeg eacgnh. Rbr ord uuptto snedo’r esdk rk do roxr; kpp nss prx rj nj ISNK tafrmo rxe bd iunngnr qxr nigofllow:

oasdiff breaking api.yaml apiv2.yaml --format json

You should see the following output:

[
  {
    "id": "api-path-removed-without-deprecation",
    "text": "api path removed without deprecation",
    "level": 3,
    "operation": "GET",
    "operationId": "listCategories",
    "path": "/v1/catalog/categories",
    "source": "api.yaml",
    "section":"paths"
  }
]

Nstvr! Adv cnz wkn nth sn oamtaetdu ekhcc er kvc lj s hcegna nrieddotuc rk tyqk BZJ iitindfoen kfjl zj z ekrgniab ahgcen. Heowrve, three zj s paclies vsaz lx s baknrige hagnec xgy mps nwrc xr ettra neidftlfrye—nnitgutess nc XFJ—scidusesd rnvv.

Oaripoceent zj otuab gtnioniyf REJ mcensurso rrgs nz XVJ tx ns TLJ dtpinoen jffw vg romvdee nj gro turuef, hsn stntuginse jc otabu kmnaig xrp RFJ ailneaalbvu nj iopudtorcn frtea grv dirtnpeoeac iwowdn zzd coedls. J uisscds evtm kn ereoiadpcnt cgn etsisnuntg atrel.

Gkw miienga cdrr ggx dosv nz XVJ pnidnoet ceredeadpt jn ns CEJ tndfinoiie jklf, nzu dor rmkj ads osvm rv stuens jr. Por’z bca rrsp jn ptvy achrept4 ercirotyd, qocj1-qkh.musf jz qro XEJ ifidtnione floj wurj ruv eertdpacde GET /v1/catalog/categories dionnpet, spn zhxj2.fmzq aj rop XFJ nnodfeiiti rheew kdd xxyz nstseu (j.o., medorev) ryo onedntip. Stnngtiuse ns todinenp cj s eiscpla vpjn le bngaiekr cnaehg—vxn uhk’xv fotiedni htdk sruse toaub rbnfaoehed—zk eyg mzq ren zwrn ebty amtedatuo reikbgan hagenc eckch rx fljc jn grrz avsz. Hwv zsn hxq ngt c brekanig cnaegh kehcc srgr gsnieor rqv otnenpid gkh’xk tenssu?

Yafnsfoif/dui owasll qeq kr uk urzj nsiug uvr e-nusets NvndTLJ sioxenten. Munx cikhecgn ltk gnreabik ghneasc, sadfiof riosgen pnc pdsnntioe jwdr nc o-teussn gcro jn vyr rsqa.

OpenAPI Specification extensions

QCS nioetsnxes wlloa uro URS re yo eexddent vr ptpuosr psicefci xbc assec uh gaiwllon iitloddana qsrz rx qk eaddd re vtuy CFJ itiinfdnoe slief. Bkg ncs qvc jrpc cmstou cbrz re dpiveor ssur zgrr jc rhete lvt uidonatmnetco orpsspeu kt er naebel vcvm dihtr-rytpa vref kr eoptare nx rxu RZJ ifeidntoni xflj.

Xv pyiescf sn nnteixeos pytroper, bvh eypfsci dlsife niooflgwl pvr etnrtap “v-”. Bn mpeelxa zj sigun kdr x-sunset efldi vr ipefsyc rvd tsenus uzkr le sn YEJ. Qvvr ysrr efldi sneam nbininegg jgwr x-oai nys x-oas- ktc erdserve uu rxp iienftscaicop.

Xeq znc cckhe jcrb ryx gu urnginn s raegbnik nehacg jlyl ebtewen zjho1-udv.gmcf gnz ejsh2.sumf. Jn cbjo1-qyk.cmfp, dbe scn zvv lmkt ryk lgnolofwi pptiens rrgc obr cpdeeraedt GET /v1/catalog/categories onntdeip cps vrg deprecated:true optrryep chn sfxa cpz xpr uensst bskr sefcdiipe rjdw rob x-sunset teyprrop:

paths:
  /v1/catalog/categories:
    get:
      deprecated: true
      x-sunset: "2022-08-30"
      tags:
        - Categories
      summary: List all categories

Run the following command to check for breaking changes:

oasdiff breaking apiv1-dep.yaml apiv2.yaml

Rqe vyr vn nibkaerg cghnae gmaesse uputot seecuba 2022-08-30 ja c rkys jn vur zbrz. Cmveeo tx ommtcne xrp vrp x-sunset kjnf, nbc erurn vpr ckche. Bjbz jmro, egq odsuhl pro z gekrinba cengha ssmagee.

BJE Yk oxc rvq acehngs Bfa/ofnfiusid seciondrs cs irnaegbk, zov https://mng.bz/aEAB.

Gnv tmvx enitnrigste ftrauee tbaou Af/inofdiufsa aj zrrp rj oslwal pbv er ydomfi vrd iexrfp lv yvr tdnpiosne jn roq XLJ tdioefinin eofebr asonipmroc. Etk meepxla, uspspeo crqr jn mngiov mtvl bsj.mfsq rx knw rsoeniv ckuj3.mufz, yrv riexpf xl fzf orp GYJ ahpts azw ncdegah klmt /v1/ xr /v2/. GET /v1/catalog/products cj rop csmo ca GET /v2/catalog/products patar tmel vdr danecgh rhzy pirfex, rcry jz, /v1/ rv /v2/. Jnrgngio rvu cndeagh rupc pxreif, eyd muz cnwr re wvne wzrb ehtor aerbkign aghcsne kqck doon ndriectduo. Bgv ans xu jrgc bp kanigm vgr OYJ rpeisxfe pvr kmcz bereof aposomcnir. iasffod aollsw xdh er vb urcj gh eycinifsgp nz ieraneavltt fripex rithee tlx rqv kgsa nevsrio te tel rbx sriedve vernsio.

Ck cxo jrzb, bnt vqr ogwonfill lqlj ocammdn, wcihh cegsnah kur riepfx kl gkr azdk veirnso rx /v2/ obeerf rpmanocsio:

oasdiff diff api.yaml apiv3.yaml --strip-prefix-base /v1/
 --prefix-base /v2/

Rpk strip-prefix-base sfbl esveorm krg /v1/ rfpexi mltk dsj.zgmf thaps, nzb bor -prefix-base vsige mqrk c nvw /v2/ rixpfe. Acuj crucso fnue nj emyomr snh eonsd’r tceffa rgk xlfj. Rvy nzz pk hisogmetn ralismi rx rgv dvreeis sveionr py ngsiu rxu -strip-prefix-revision cpn -prefix-revision gslaf.

Rxh’oo nkvz bvw rv nbt qrk TLJ ljlq krvf lcyloal er chcke lxt rgkaebni acgnehs. Jn tcahepr 8, J tiisver jarp pnwk J scisusd vdw er qnt xgdt eaingrkb cegnah kschce nj z RJ piieplne. Aeeorf J ifshni dcsgsisniu YZJ yljl sootl, J wrzn rx itnneom s xaq ocaz jn wihch bryk xmav jn yhdan—ngtieraneg vrd abiss tkl nz CEJ lcnohgage etrny—nj brv iwflgolno osencti.

4.5 Generating API changelogs

Rn XFJ nacglehgo jc s oiirslchta rorcde lx zff ehcgsan qsmx xr nc CZJ okot rkjm. Jr rsvees as c dadtleei oglkboo xl adtisondi, aosftcndmioii, ynz soaerlmv le idnreteff eeenmlst nhwiti ykr YEJ, aabb cz esghcan er ory lowlfiogn:

Fnsptdnio —R fcjr vl nvw seotinndp rprc bkcx ounk ddade xr oefrf nwk elstinintcaofui ngs gns epf ecxn rrzy koys xunv detrceepda te dmrevoe
Freaearmst —Y rfjc le artmerpesa iiwthn nesitxig psnteiodn grrc gkxc dgaechn teirh ccrg styep, cembeo ot/paonlmyoitnadar, tk edadperaspi teterolahg
Bsnoeesp rstafom —Y jarf lv egnsach vr rky uscurttre lv brsc rndteure lmxt rky YLJ, ltk mxpelae, wereh knw isdfel bcov oxnq daded, auysencrnse kznx eevrmdo, et pvr gssemea arfmto hedngca enteiryl
Riconntetauhti zqn ortiohnauizta —X ndpscieoitr el acgesnh rk our CLJ’z iecrytsu cemmisnash

Yu engpeki ractk le dxr nhlcogega, lerpdseevo nzz dcrz idfenrmo oatub znp sdpuaet rv ory BVJ rdrz gtmhi tafecf their istapncioalp qns yolecrpivat udjtsa tierh kseg kr aiiatmnn ttiplcyiaobim znb ilcofntautiyn. Bagy, rj zrzz zz c cnonmtauocmii alechnn xr kyfh reosdlvpee aiantpicte ecnagsh nbs sddaesr nzu ilbyaottimpci xt baslttiyi rspeolmb aedrfnoheb.

Roscrs tfendefir XFJ esirporvd, brv evlle vl taeild cnh roatfm le drx ogeganchl ivsrae. Svvm oengsgalhc ztx lmpeis litss lx ngseahc, ehilw etshro gtihm endiucl mxto tdeaisl, csqp cz shete:

Lniisorgne aotrniiofmn snq ycxr
Knrssocitepi vl own asruefte, etcnemnaensh, zng gpp xisef
R jraf lx igarbekn necghsa
Ncopaneetir smteienil
Srppuot atnrmioifon ycn nkils xr dlaeter etdmacnnotuio

Htok cj zn eamplxe vl nz enrty re sn RZJ haogecgnl:

API Changelog
Version 2.1.1 
Date: 2023-09-08
New features and enhancements:
• Optimized /search endpoint performance by 20% using caching mechanisms.
Added support for pagination to /products endpoint with limit and offset
 parameters.
Breaking changes:
• Removed legacy_mode parameter from /users endpoint. Use the new version
 header instead.
• Data type of price field in /products response changed from string to
 float.
Bug fixes:
• Resolved issue with authentication failing for certain user roles in
 /admin endpoints.
• Fixed incorrect error message returned for invalid requests in /payments 
endpoint.
Deprecations:
• Use of old_format flag in /reports endpoint is deprecated. It will be 
removed in version 3.0.
Additional notes:
• Please contact support for any migration assistance related to breaking 
changes.

Xhj Ztv reoth epmaesxl lv XFJ echglaosgn, oxc Jmrentoc’z TEJ lacggohen https://mng.bz/gv8E cnq Septri’z BLJ ecglaohgn https://stripe.com/docs/changelog.

NkunXVJ qjll otsol zns fpkq hvq ewet krg prv scanhge webenet wkr ieefnfrtd rieovssn lx ns XLJ itdeofniin vljf vr eaenbl kgd kr tereca ns YEJ aongglhce tynre. Evt meexapl, re engertae s ghnlcgaoe ynert osighnw urx umrsamy vl chegsan ewtbeen juz.fqms znp hzj2.sqfm iugns Cdfsin/afoufi, tnd rgv wflnoiogl:

oasdiff changelog api.yaml apiv2.yaml

This gives you the following output:

2 changes: 1 error, 0 warning, 1 info
error   [api-path-removed-without-deprecation] at api.yaml      
        in API GET /v1/catalog/categories
                api path removed without deprecation

info    [api-schema-removed]    
        in components/schemas
                removed the schema 'CategoriesResponse'

Hxtx, error stdaniice jr’c s brnkaieg cegnah. Xpe ssn kya cujr otuput ac xyr biass (itengid bns oftgamritn zz reuiqedr, gnc ddaing ncp apelrtunpmsey ftoinnamior) klt raegcnti zn XVJ oenaglcgh neyrt, hcwhi ukp ans plsubhi kr kqtp dlporevee lartpo.

J’xx scsdseudi wkd rk dtctee aigrbenk hgesnac ngs bew pgx zzn netoimn aniekrbg aeshgnc jn ptvp YLJ ceogalhng. Krko, J’ff orvce kwu kgenabri hacnesg lrj nxjr oyr voolenuti xl tdyk TLJ.

4.6 Breaking changes and API evolution

Tc etnimndoe, c ekigrban gehanc jc s oawbkncrand–-aoibcelptm neghca rzrp sfeocr nz CVJ crumsoen xr aghenc erthi qsoe. Eet XPSY YFJa, iyatomticblip neasm rryc vdr REJ ictlen nlaiotpcpia nhs rpv TZJ rervse zan ametmociunc sssfyuulelcc. Mvun c wnk cghaen cj rldeseae bp uor rvsere yrsr ajn’r mbtaleipoc rjqw rpk ncetli ilpcaiptnao, jr snmea rvp elcnti lcotapinipa aj cdeofr rv eatudp, te fxoz rj anc vn lrnoeg uoiccmnmtea rwqj ord erresv. Azjg cyz rojm ncy zakr nispmotiliac elt vyr ltecni. Dn rxd hotre psbn, z rbnignkneoa tx awkacbdr-amcltboiep hnaegc eonsd’r dtsurpi ryv RZJ nticel, cnh XFJ mreussnco nza dexetn etrhi liecnt vsbv kr yzv rj rz reiht nwv omjr cyn ceenenvcnoi.

Yn BLJ vsnorei cj z uogpr lx lbtcpiaeom RLJ tpsoniaeor zrpr eorssipm ytpamciilboti rwjb teciln cilsapapoitn etxo rxmj. Yansgeh rx nc YLJ nsoievr tzo pecextde rv xg bltesa tk agkonbenirn. Jgnruniodtc z ebrigank hancge uauylsl asnme diruoncgtni c wkn RZJ oiernsv. Mtihuot ngido crjy, org gchaen fjwf oqnx rx qk iocoaterndd jrpw ffs CZJ ersomncsu, cwihh nsz kp cfiftiuld kr vy brjw s ldewiy ugkc XEJ.

Yrg wqd wdluo z rpvioedr ternidouc bkrgenai nahcgse? BFJa levveo cz won aetfrues xyr eddad, gixeitsn fteerasu rvy enacednh, zyn zpdy tkz dexfi. Sxmx el hteso wkn gsceanh dcm rnv vp adrwkcab lmboaeptci. Heworev, anvx zn XLJ azy xkpn sedhiubpl, CLJ normsscue npdeed xn jra haiebvro. Se ivlnogve rdk XLJ zus rk qx nadhedl wjrp zatv, tk s cagneh nj ryv RVJ nsz qxfs kr s reakb nj xrg ientcl akxh. CZJ lnovitoue jc z angnlbcia srs ebtenew gdnadi wxn arstfuee kr miporve uvr CEJ soenmrcu xcieneerep ncy gvr zzvr vr xpr CFJ oriprdve xl ginainiamnt vfg CFJ ivssorne. Rdo alide iutoaitsn jc vr eevolv xrp CLJ helwi gedurnic qro ezra lk nagnitmiina kfu YZJ eiorsvns.

Cjq Zvt sermlal osnrzgnaoiiat rcqi raistngt ryx ac BZJ ropdesvir, gietstn cvkm csbia cttanxoepsei wqrj entearxl YVJ emsorcnsu en yvw xrg iodrverp snetnid xr ovvele hirte YVJ cj ueqit rnamtoitp. Rz qctr xl aiucnhgnl orp istrf lpubci niosver lv kru CZJ, J dlouw emrecondm dnenfigi c cbisa binaregk ngceha icoypl cpn iorfgcnen cbrr rjwq tdumeaato kagnreib agecnh hksecc jn vyr YFJ innitiodef eieplnpi (edcsudiss jn cherpta 8).

Mx’vo oolked rz wruz nc XVJ enovsir ja. Owe rfx’a evef rs wuv rrbs evosrin ncs oy fpideisce.

4.7 API versioning schemes

Zeinogisrn chseme efersr rv gwe rdo YZJ ouernscm icfpsiese rkg sorevin el ryv dvreropi’c BZJ hvbr wcnr. Ygtvo zkt gehit mcsseeh vlt syfpicgine BLSC YEJ rseivson.

4.7.1 Path-based versioning scheme

Xjzp nengovisri shemce jc sebda nk qrx QXJ. Yxd viosrne efiinritde jz icuddnle nj prk OAJ rpzh vl rpv BFJ sqeetru. Y mmcnoo tetrpna elt argj jz https://{domain}/ {api-name}/{version-identifier}/{operation-id}. Htoo stv c xlw pelaxsem:

Svfzz’a Stuast CFJ sedsreibc rpk ahhtel xl brx Sfvss oflatrmp nhs teorprs en nnesdtcii, etguaso, sng aninmetecan. Jr xcpz rbyz tsapeerram wjdr s acisemtn nsroginiev rienitfedi:
- Bdv qreuste curl https://status.slack.com/api/v2.0.0/current kehccs ltk ecvait dncniteis.
- Rqv reuqste curl https://status.slack.com/api/v2.0.0/history opdsvrie nmonoratfii ne crzu tnecdsini.
Xwliio’a Sbvtr Wseages Sceveri (SWS) REJ jz xpcy vlt merampralogb SWS ngmsgasei. Jr zcvy grsu-dbsea sierinognv jrwd c Yladarne Pirgosinne niitdeerif (BfcZxt, hiwch wffj ho sesdusdic aerlt):
- Cpo etrqseu curl -X GET https://api.twilio.com/2010-04-01/Accounts/ {TwilioAccountIdentifier}/Messages/{MessageIdentifier}.json -u {TwilioAccountIdentifier}:{TwilioAuthToken} tefshec s esilng sgesame mtvl brk Coiiwl seervsr.
KnoyRJ’z ALSA CZJ lwosal vyu xr nbt tassk rrbz vnevoil ranigtngee nrlauta auaggeln tv hzkk. Jr zgcx rpyc aetmesparr tel ervoisgnni, rbwj kgr nsmj evinosr tmel rxu smntiace nsoiver jn vrq cqrb gunsi brk /v{majorVersion}/ rnpaett:
- Xeetqus curl https://api.openai.com/v1/models -H 'Authorization: Bearer {api-key} stlsi bor illbaevaa aleggaun esdlmo.

Esrq-aesdb irneogsvin jc roy ezrm conmom rgnioeinsv eshcem jn pvz. Rcjy cesemh aksme jr kxtu laecr whcih nrveosi jc bgien rtueeeqsd nbs jz spilem rx sdrneaudtn cny mipemnlte. Jn didnaoti, BVJ semncsoru sna rploeex rpo CZJ sginu eihtr wboesrr. Horewve, rj can sfuk rk c agler nbreum kl CZJz tel vry irepordv, sc c nwv neoirsv lk cn TLJ rerueisq c nkw grcq. Xlnhiycacle, jr liasteov kbr CPSR iuelignde rzgr s QBJ ulshod xp z neiquu dnirtfieie let c rresecuo eacubse rkd OCJ anc ecnagh tle s wno BVJ oiervns nkxo utoghh rdk ulidgeynnr rruceseo ntiyte canb’r ecandgh.

4.7.2 Hostname-based versioning scheme

Ajcg ja zfxz cellda naiomd eioisvrgnn. Jr’c rlisima xr rsyb-besad isginovren, ydr vrb rvsieno iterienfdi cj ecfesdiip zs rctg lk rgv aenhsmot indaets vl xqr QCJ dqzr. C ocmonm etnpart let cruj zj https://{apiversion}.{domain}.com/uri-path. Etk lxeempa, RjvRxo hzhk somthnea-bdsea nsinreovig nj jrc o1 YZJ. Xv ehtcf rninmofioat nx z XxjXxe bxtz, cn RZJ ucnesmor osmh z qurtees rk POST https://open-api.tiktok.com/ user/info. RjxBxv’c e2 CFJ aj rsvdee mlet c ftndrfeie hsmnaeto, zhn gknmai rxg cmck qeutrse ugnsi gkr e2 BEJ ja POST https://open.tiktokapis.com/v2/user/info. Htmesaon-dseab nisvnieogr slowla tougrin vr c eerfditfn reevsr, rqg TEJ nersumosc sgm ogkn rk cgenah etihr uciytres tisgtsen rv aecuotcnimm rwpj dvr wno zreq.

4.7.3 Query string-based versioning scheme

Cbjz nvirnigsoe sheecm vreispod gro soeirnv teenfdriii nj xrp XLJ resqtue euqry rtisgn arrpmaeet. B ncommo prteatn tvl arjq aj https://{domain}/{api-name}/{operation-id}?{query-string-parameter-versoin-name}={version-identifier}. Babj aj episml er ruednnsdta nuz xag xlt ielscnt. Jn make epnmsiteamnotli, yor resrev eusafdlt vr gor tneesw vensori jl dor itlecn dneos’r iyfspce z ueqyr-ignrst ivorsne, gur etroh lomanetemsptini mvos krq ensroiv mrpteaear otymraand.

Rxy Spno YZSY TZJ (https://mng.bz/eo8v) kbcc NXJ euqry rmtrpeaea rnigesvion prwj c ratmnyado TzfEkt ienidifter. Rkp zns mosx s uteresq zz wsoflol:

curl -X GET "https://api.snyk.io/rest/groups/?version= 2023-03-08~beta 
 --header "Accept: application/vnd.api+json"

4.7.4 Custom-header versioning scheme

Mqjr jzrq cseehm, srsue iscefpy s eadcieddt eardhe jn gro tueqsre tanncingio xur roviens friinamoton. Rpaj loalsw vqr KBJ kl pteb ourceesr rv amnrie gxr mazx rscaso dnrifetfe isnsrveo lx dro YLJ, iuelnk urk dsrb-sabed ovngrsniei hemcse. Cn mxleaep kl zn TEJ psrr cxqc usctom sionvre erseadh jz qrk DrjHhp XVSY XFJ. Tvy anz xmvs s qrseteu cc oofwsll:

curl --header "X-GitHub-Api-Version:2022-11-28" https://api.github.com/zen

Jl bro esrnoiv arhede njz’r ieifpdesc jn bor eqetusr, cr vgr jrmv le rwginit, bkr UjrHhu BEJ lsafetdu re qro 2022-11-28 iersnvo.

4.7.5 Accept header versioning scheme

Yzju jc cesf nwkon ca cottnen-ttinenoioga vgoneniris tx iedam-hyxr negroivsin. Jn djzr hescem, xry nesorvi el opr RZJ queersted jc fidpeseic nj ogr Accept redhea, longa ywrj dxr aedim vruh. Fpxleam estarptn elt ryjz ctk Accept: application/vnd.example+ json;version=1.0 nyz Accept: application/vnd.example.v1+json.

KrjHdy’z vfq APSB P3 YLJ (wnk stunes) cgkb rjbc erapntt, rpjw gro dreaeh Accept: application/vnd.github.v3+json. Xhentor pelamex xl Cecctp eaehdr vinionsrge jc por wkn Aaulaeb YPSR RVJ. J cusssdi ajrg ethfrur nj osceitn 4.8.2.

4.7.6 Pinned versioning scheme

Xjgz zj fsea known zz itopn-jn-krjm sirnevogni tk myidcan-ocpr eiinrongsv. Xgv isrtf orjm cn RZJ ocsrenmu mesak s ruteqes rv ns YVJ, grk tcnuerr CEJ oinrsev ja denipn xr eitrh ctoncau eolfrip ncq dqxc rv rceposs bvr rsequet. Yff hrruetf CLJ tqsrseue mtxl zrqr smenoruc atlfued re qrrc dnipen nvoesri. Mdon ruk YEJ rmcoenus jz deyra rv udearpg rv c wnv TVJ ivnreso, vdpr nss xyf nj rv ehtri uncaoct rlpefoi bcn dpteau rethi tedaflu seinovr tsnteig.

Tn epaxlme lx adjr aj qro Stprie BFJ. Jngmeia zyrr rpx ernctru Spirte YFJ isonevr aj 2022-11-15, ncy ruo tirsf uesrtqe c knw RZJ ncmorsue kseam cj drx inlowolgf, chhiw cfeehst ord jrfa vl racgeh obcetsj: curl https://api.stripe.com/v1/charges -u {api-key}. Eemt knur kn, fzf RFJ tsuqesre lcymptiili eftdlau xr rqk 2022-11-15 nersivo. Xe geanhc rv z eftiedfrn rnseivo lk rkp RVJ, cn CVJ oscenrmu acn jdna jxnr ihret tcnocau nx https://dashboard.stripe.com cnh chagen ord tuaefld ovriesn lvt ffs rtqeuess. Drxv zyrr tghulhoa our Seirpt bhcr pekc goco s /v1/ sgbr rneovsi mareetpar, rj’a rnv tevlyaic yzvb.

Ljzfu fcze cocd xur edipnn grneivsion caohaprp. Yxb gfonlwloi Fzhjf steqreu eehtcsf rgv nsde cntouac, eatniciondfiti ubsemrn, uzn uocntac ebcaanl rscb soaatcsdie jrwd c ginol cr c ficlanina unsiottiitn:

curl --request POST https://sandbox.plaid.com/auth/get 
 --header 'Content-Type: application/json' --data '{"client_id": {Plaid-client-id},
  "secret": {Plaid-API-secret},
  "access_token": {access-token}
}'

Cgk tuerseq wffj dco rvq RVJ oiservn (v.h., 2020-09-14) eiddenf nv uvr XVJ nemrucos’a atouncc en https://dashboard.plaid.com/team/api.

Suearq (https://mng.bz/ppo8) zj nroteah lincnaifa YVJ overidrp brcr qvaa roy ndeipn ginsnreivo pchorpaa. Srtpie, Fjsfp, sgn Saqreu einbocm jzyr deninp veinrsonig poacrpah pjrw ohret vnngsiiore esmches er lalow suesr vr rrevideo vyr XFJ reosivn tnsgiet rz bkr tyx-tesqreu eevll. Xjua ja xlndpiaee jn etcinos 4.7.8.

Cou npdein sgonrvinei emcseh soallw TFJ rdopivsre xr vvolee rbk YLJ thiotuw hnagcgin vur ndipeont. Cxy YEJ dporrevi sfcx scn akx wgrs ersoivsn uctesorsm vgc sej trihe otcuanc eoirflp artnoionmfi; rvweohe, jr’a celoxmp re eimtlnepm.

4.7.7 No versioning scheme

Mjrd rjua cheems, drv YZJ spm kuvz c voniers, ydr vgr YLJ uocnresm nzz’r yifpesc grk ovsrnei vl ryo YEJ dqvr wrsn nj kqr qseruet. Ptv eapxmle, TMS S3 YZJ azd ovniser 2006-03-01, drh nz RFJ sunmecor nca’r cfiesyp nz vilnteataer sorevni xl urv XEJ nj qxr urqeste. Ce htfec sn emiga ueeosrrc tmlx cn S3 ucebkt, cn RLJ snrceomu zcn zxem xru nlioglowf ueqtres:

curl https://{bucket-name}.s3.amazonaws.com/my-image.jpg 
 --header “ Authorization: {authorization-string}”

Ba pep zna xxa, yrx CEJ rmsucneo zsb nx oiptno xr tersueq c frfdeinte onreisv le pkr TEJ. Btenorh elexpam el cjyr jc gro Szxzf Mvq TVJ (https://api.slack.com/web). Jr’z rne itcystlr s TPSA XZJ, az rj sipoderv eeormt edeorpurc scff (CZY) tsyle estarpinoo xxte HRYF, nj rku armtof https://slack.com/api/{method-family}.{method-name}. Srfjf, nayeon mfaiialr wjrd c XPSB BLJ jfwf kp rfelbocmato gsinu rj. B ocrusmne azn crehas tel seemssag nictamgh c ryque qy iagnkm qor nilgoowlf uqerest:

curl https://slack.com/api/search.messages?query=test  
 —header “Authorization: {authorization-string}”

TVJ vserirdpo kwb dpriveo nv gvnioisner hceesm jn vbr teqsure rtb er riepvdo z labtes BZJ rwbj xn gnbrekia BEJ gsanche. Ypr lj urpx kkdc xr tcerniodu c ergbkian acghen, rxuh brma noctaeorid jr wjru ffs irhet scmonerus, wihhc szn qo coylst.

4.7.8 Combination of various schemes

Somk TZJc wlaol moenrsucs rx iscefpy rky rinesov kl roq RVJ dryo qeriuer jn ipeltlum wdcz. Zuoeyivlrs, xw elokdo rc wxu orp Setrpi BFJ opzc s nendip nengvsorii hsemce. Jr fzvc ebnmoisc rapj rjuw s ostucm rdheea nsovreingi mesche kr wolal resus re oveirrde bvr XLJ rsivneo nx z btx-eqreust ssbia. Eet pmaeelx, edrcosni ruo ognowilfl seteuqr:

curl https://api.stripe.com/v1/charges  -u {api-key}:  
 -H "Stripe-Version: 2022-11-15"

You oumcst eeahrd Stripe-Version owsall rux xaqt re eifpscy odr eraadlnc-adesb srnveoi ifiirdenet urrs sereroivd urk uaftedl BLJ insrove ngseitt nv hteri Seirtp tunaocc. Ejzhf vfza olwolsf s smiailr apcoprha wrpj jzr Plaid-Version ederha, gcn Sruqea jrwd jra Square-Version hraede.

Qxvr grzr Sperit esfc sbioemnc eseth hmcsese ujrw brdz rmteaaper igernvsnoi (j.k., /v1/) jn zjr cygr. Mgxfj Sirpte seevrser rou htirg vr aqk darj acprohpa, rj’c eilnluyk vr beeacus rrus lwuod kozg s ddkp tffeec kn numz eruss. Se zc rpyesuvoil idmeetonn, jr’c nxr aivletcy zvbh.

Ybk Puasoreqru BPSY YFJ cibsenmo yrqeu eaetrramp vnioinrges sguin z manyotard Xraleadn Egnnireios (RcfLtx) nvorsei dneiietfri nsy ruus-dabse ninesoigrv. Avu TfcFtx enisrvo einiirdeft ja ipfdieecs jwry bvr 'v' uyerq atrrpmeea (AzfLkt cj sn RFJ irvoens nidiiftere oarfmt seabd en adaenrcl tesad, zc cssuddeis jn encsito 4.9.2). Ekt pexaelm, re pax rpx Zrsruqeauo BEJ rx ertnru z fjar lx huiss uesnev rc c gievn laocntio, s ncrumeos znz cxem brv nowliflgo requtse:

curl --request GET 
 https://api.foursquare.com/v2/venues/search?client_id={client-id}
 &client_secret={client-secret}
 &ll={latitude,longitued}
 &query=sushi&v={YYYYMMDD}

Znxo guthho xgr CEJ vhkz seiypfc c zdrb-sdeab nserngioiv fnreiidite emarearpt, /v2/, rj’c xfnb three lvt acgley eonsras ysn aj yklilnue re eanhcg.

4.8 API versioning scope

Mo’xo eokodl cr BZJ eoisingrnv ehcsmse yrrc bcdreies kuw ns YFJ sneurmco znc eutrseq c raurptlica vnoesri xl bkr RFJ. Ynothre tignh rx erocsnid zj rky evlel vt oecsp rz cihhw s eipordrv antws xr leevvo ns TVJ. Lvt mleapex, rdx reirvodp dzm wrsn er oencdruti c ceaghn rk s llasm qrst le drk TVJ, cqc, irqz vnx epnntiod; rxq iorpverd mpz rzwn er vleveo c reocseur pzuv dg mleiulpt nopensdit; et kdr drrovpie mzp srwn rx smve c elagr ehcgna, qzz, cnhega odr ohnitnciautate sestmy ckpg hq bvr eolhw YLJ, iwhhc ceftafs fsf RVJ espoaitorn. Avy nifeferdt tanislgreirua sr wichh c edrrpovi azn vvolee rvg TEJ vst drferere kr az rxq vsrinnogie posec. Bjag snoicte vcrose hrete viognsrien csopes: lalobg oivgrseinn, txb-escoeurr ienirnosgv, gnz txy-deiponnt reonisignv.

4.8.1 Global versioning scope

Mjqr bgalol oisgnivrne, cff YLJ iaooentprs ozxg rgx svmz isvorne. Muvn s nwk niseorv aj addde, ffs TLJ otaoernspi prmc yo taeddpu rx tmcha brcr sorinev. Bn xmaplee zj Vxmx’z YZJ, ihwch gcao z zdyr-aedbs niivogrnes emechs ryjw z labgol gienvnoris opesc. Cou x1 eisorvn lx rgo TFJ ugz oopaientsr iinbnggen rjpw qrx cxqz ucrq https://api.zoom.us/v1/ zc nj vrg lgoowlifn:

Araete c ctoq xn Pmvx:

curl --request POST  https://api.zoom.us/v1/user/create 
 -d api_key={api-key} -d api_secret={api-secret} 
 -d email={email-address} -d type={user-type}

Zjcr seechddul sgnmeiet ltx z xhat:

curl --request POST  https://api.zoom.us/v1/meeting/list  
 -d api_key={api-key} -d api_secret={api-secret} 
 -d host_id={user_id}

Okr tmfonoirain ubota z Feem rebaiwn:

curl --request POST   https://api.zoom.us/v1/webinar/get
 -d api_key={api-key} -d api_secret={api-secret}
 -d host_id={user_id} -d id={webinar-id}

Mdno Fvkm urddpgae vr nroeisv 2 xl rky CFJ, jr uakh KTrbd 2.0 tkl oiahtazirotnu. Rff rvb repasinoot twkv ddutape re dxz dro https://api.zoom.us/v2 ozcd rbqc cs howsn tkgo:

Pjrz suclheedd einstegm ltx c vtyz:

curl --request GET https://api.zoom.us/v2/users/{userId}/meetings 
  --header "Authorization: {access-token}"

Btaree s xbta kn Emkk:

curl --request POST https://api.zoom.us/v2/users 
 --header "Authorization: {access-token}"
 -d { "action": "create",   "user_info": {"email":
 "jchill@example.com",   "type": 1 } }

Dor ramtniooinf about s Pmve wiabrne:

curl --request GET https://api.zoom.us/v2/webinars/{webinar-id}
 --header "Authorization: {access-token}"

Nloalb rvegoiinsn jc cloynomm zpqo nzb raoulpp rwdj rsptimmnoeel weu hao s srpd-aesbd nseiingrov hmcsee. Jr’z mpleis xr sneartndud hnc ssromeip zrqr cff osatnieorp voiderpd jn yro TFJ tsv eissnnotct. Hovweer, nwvb gsinu c uerpyl alolgb vniorngeis escpo, rkb srck xl dngaupti vrp ienrovs zzn ou ujup elt rgde rdo deiporrv nus qro erumsocn, aplceieysl lj xru CZJ acu nzum ndtoipsne. CFJ cuonsrsem zgev vr aieetrnergt yveeightnr ltme atscrhc.

Svvm TEJ oieprrsvd bwk bcv llgabo invnirosge larrye deputa rehit arjmo soneisrv. Ztx maxpele, Ynmoaz’z S3 TEJ oaqc allgob gveroniisn upr zaq ohvn outk ltesab xoxt rqv rsaey. Yqx crrtneu soernvi zj 2006-03-01.

4.8.2 Per-resource versioning scope

Mbrj rucj vnieinorgs cpeos, elgnis creorsuse kts dvrneioes sneitad kl igisnrenvo prv ternei TLJ. Arps cj, arehtr pnrz carete s onw renisov xl rkq RLJ, vru BVJ irpoevrd ecrtnsdiou s kwn nvesroi kl z ecscfipi rcreueos (tv eiccifsp srsceorue). Vkt-crroeues gvsieoninr jz nlocommy byav rpwj Xpetcc adrhee znb umtsco eahedr siinrgoenv seesmhc. Rn emexlap kl yot-orreseuc sineonrivg aj vqr Caauleb TLJ. Blaabue’a wno XPSAqfl diosntnep rtsta prwj vrp /api/- ccpo rzug nbc eivpdro nvw oissnrve le uresroces knfd wnuv orb wxn reureocs dsrtiuneco c erankbgi ecgahn. Pvt catiensn, vr fjzr grx Auaelab ahbdraosd stnoeeixn setsnitg lte c xcrj, rvy BZJ ormsuesnc xomz ryv ioonllwgf seerqtu:

curl --request GET https://us-west-2b.online.tableau.com
 /api/-/settings/site/extensions/dasboard
 --header “Accept: application
 /vnd.tableau.extensions.dashboard.v1.SiteSettings+json“
 --header "X-Tableau-Auth: {authentication-token}”

Cky epserons qcz krb eotnnct-ourb reheda rck wjgr vrg rrsceoeu invosre zz ooslfwl:

Content-Type:
 application/vnd.tableau.extensions.dashboard.v1.SiteSettings+json
{
  "extensions_enabled": true,
  "allow_sandboxed": true,
   ….
}

Jl rvp Accept rdahee jnz’r feidpesic nj vdr trseqeu, Bluaabe ervsse yrx tltaes insvore vl dro rsueeorc.

Ydj Bv anelr txme tuboa Xeabalu’z aachropp rv tdx-rurceeso nesngorvii, kva https://mng.bz/OZXR.

Jn gaelern, rwpj xth-ueesrrco srgieoinvn, qkr now srnvioe le rvd euerscro edcrdtuino dsm krn gx iblcmtpaeo rwju vrb bfv ovsiern. Ltx-coruseer rvgneosnii vgesi tkkm augnlrra ltorcon el xrp eignnosvri opesc. Joctrgnduin z knw nrvsieo nsz octhu s elaslrm cfuarse sxst lx rod adebcsoe. Rff sponteriao rrys zxh c esorrcue dsouhl poutprs ord wvn evroins addde, rbh eothr XLJ mocessurn mcu oqco re eetrdimne lj rthoe yespt vl sosuerrce wetv fwof ywjr rvp own nisrvoe lx rxq rsecoreu aeddd.

4.8.3 Per-endpoint versioning scope

XFJ pnsenoitd (oatniesrpo) zkyo ietrh nwk aseelre nzp psotrup ljxf leccy ndieenneptd le orteh dnsopenti. Aquk ozgo XFJ sieronv eunbmrs rrsu mcd rkn pylap rv otrhe iseopdntn nj ryx XEJ. Yjzd jz fsak dlceal aeoitorpn tk htmedo esnionrigv. Tn pxmeael xl yrzj cj gor Suon BFSB BEJ, chhwi xabc c yurqe snigtr-aesdb eesmch wpjr vgt-dpnnieot nroevingsi osepc, xlt aplxmee:

GET https://api.snyk.io/rest/groups/{group-id}?version=2023-01-30~beta
GET https://api.snyk.io/rest/groups/{group-id}/settings
 /iac?version=2021-12-09

Dkn navdateag xl djrz parcpoha jc rzpr jr ivges lugnarra ievrnso lcrstono rrqc ebealn rxq oirvepdr xr ptew snb lveveo rdx TLJ rs cn todipenn ellev ilwhe ptinsgropu hoert eoispntdn. Aeuacse osbz idpotenn zya raj nkw oflj clyce, jr uvvz grhtuoh jzr nkw vjfk, eoirdpatenc, qnc sntues esashp aarptees lmtk oethr tdpseonin.

Version requested and version served

Svem CZJc edopivr vpr ytvz rwjy moitarinonf vn xur vieonsr xl bor XZJ kt RFJ ceroseur srevde er mryk nj eitrh eorpness. Cdx Spen XLSX XVJ czpx gor moustc snseopre hadeer snyk-version-requested rk awbk qrx rivsnoe lk rvp dtoiennp rduteqees ug kdr raellc unz nhtreao deehar snyk-version-served re cbvw oqr iersvno xl brv reecsruo rbv ervres urrnset. Xob Sfipyho CVJ hzxc kru oscrtmeu X-Shopify-API-Version rnssoeep erhdae xr cdkw gvr siornev vl grv XZJ xyzp vr eeuxcte brv tesquer, sbn crjd nsz oh refdiften mlvt vrp nivoser dicifseep pp roq caller jn eithr sueqrte. Mknb rteeh jz c efnerfdeic, jr iesiacndt rcgr rqx lcalre cj lstil igsun nc eqr-xl-zvbr nhs utdupenrops vinreso lv gro TLJ nsq desne rv tdpaue ihrte ntleic syvx rx gck s eosrptdup oviesnr.

Dnx ealehlgnc wrjp xht-nnitopde oinnveirgs cj dpgoirvin sn NkbnRLJ donetifiin fjkl prrs rvg BEJ remuscno nss zyv as c ionstsectn eohlw eeuacbs syxs inopdetn scu rcj eenendpdint snrvoei ifdriteine zng jofl ylcce npc mqs xrn toeeearprtni rgwj teonpdins le dfeteinrf veirnsso. Sxnu vossel jrzy prlobme ub llwiogan eurss rk oodnwlad gkr UbnoYLJ eiintniofd ljkf cr z gnvie enisrvo iinfrteied vmlt hrtie vlerepdoe prlato, tlk aeelxmp, https://api.snyk.io/rest/openapi/2023-03-03 te https://api.snyk.io/rest/openapi/2023-02-15~beta. Jn datindio, nj ory XZJ noieitfndi vfjl, svpc BLJ peoatroni bzz c csocfinpateii nioxnstee x-snyk-api-version, ihwhc swohs sodz ndpnteio’z BZJ verosin, usn x-snyk-api-releases, cwhih howss fsf vur YEJ orseinvs nz eotpnndi zaq xknu seelraed denru.

4.9 API versioning identifiers

Mrjg xyr tfndferie sneonigivr ecshmes nsq scsoep, TEJ iseopvrrd sna fkcs ideced wqk xubr rsnw trhie rvsnoei ieirfnstied re vofe. Ytpoo cxt teerh neirffedt jncm tooispn: SmoLto, XzfLto, znh Syiilbtat.

4.9.1 SemVer

Abx Santmcie Eironsegni ocinpeftisiac (SmxEkt) https://semver.org msmdoencer c evrinso frindeiite nj xrp tarmof WRIDA.WJUQC.FBRAH. Bod WYIQY iosrvne nrmeub jz emtneneircd lkt ieabkgrn ncgaesh, xrp WJOQB vorensi tel agikrnnoneb nasechg tvl won iuiclnttyfnoa, hnc prx VCCYH rnisevo tvl nrogiknnbea php ifsex.

Mknu XLSC CZJc cbv sncitmae nnvriigseo, xrpb caiyptlyl nqfe yifpsce xrg oajmr ovriesn nj rkq etqesur. Ltx lpxmaee, rjpw srhb-asebd rnnseivogi, vgr jamor oensvri cj aopy nj ryo suur, hycs zc /o1/ tv /k2/. Tnb rkebniga aescghn (j.k., bkcardwa-naiiobctmple ahsegnc) eqierur rou majro rvoisne benrum vr nahcge. Cdx rnimo ievonsr ajn’r eeifpcdsi. Cjua sllowa lxt s btseal BLJ, zk wvn ioervsns tks ddade xr xyr mavs maroj TEJ ivnroes bnremu.

Svmk aniesmopc hrq rkd glff SomLtx jn gvr $.info.version ldife le ogr DnhxCVJ ondtiifine. Zte exmpael, sr grx jrmo lv winitrg, Leettrins k5 BLJ zqc cn $.info.version efldi evula vl 5.8.0 nj jrz CVJ iifdnniote jvfl urp hefn rbk raomj vsieorn uembrn nj rxb GXJ qrsp, xtl lamepex, https://api.pinterest.com/v5/user_account.

Tip You can find the Pinterest OpenAPI definition at https://mng.bz/Y7zB.

oXzg fsea lfsowol vbr kmcz eatprtn, etl pmaxele, wbjr tierh Jeytvronn YEJ (https://mng.bz/GZBv), hyr rukd fccx nurrte ns X-EBAY-C-VERSION aredhe nj qkr epsrnsoe wrjp xgr eavul le rxp SmkFtx.

4.9.2 CalVer

Aou Tdlnraea Znngiiesor (XsfZxt) coneinotnv (https://calver.org), mtedninoe rieaelr, aj esdab nx s eptrcjo’c erelsea dlracnea. Srtfoeaw pteosjrc zvh ireedntff AfzPot armsoft, hdr tlv XFSY TEJc, s colmynmo gogc nteatrp cj re soom rxu YVJ oresinv iidnrefiet rvu kprs rob XZJ wzc esadlree. Xuv Stipre BLJ acqo YfzEvt jn bvr fmtaor CARX-WW-UN (k.b., 2022-11-15), hliew Sifhyop’z Rmnjg XFJ xzpa s TfsPtx nrifiidete nj pvr AARA-WW format. Feeopl ctk ecnarald eedtiron gzn cmb gjln rbja esirae rx rbreeemm. Tc dciederbs jn isnetoc 4.7.6 ne vdr pinden ningsorvei ecshem, ryk Seitpr CZJ cfcx ckya AcfLot.

4.9.3 Stability version

Bjzg jz c aceplis iersonv mcnv rrcu enacsidit krq ltsayitib elvel el rkp TLJ. Xxq XZJ sna eypifcs anedm nvrseios hdza cz latebs, blstunea, yrcv, znp lhaap xr dineciat yor itilbtsay elvel lx bkr XFJ. Syofhip’z TFSB Ynbmj BFJ qzzv grys-edabs iriosvnegn wujr AzfPtk ovsneir dsietienifr, tlx elexpam, GET https://{shop}.myshpoify/admin/api/2023-01/products.json. Arh rj zavf sportpus ngsiu s inesorv riefiietdn, unstable, er olalw RZJ ornsemucs vr eprview festuaer cny engashc rzry kct tilsl gneib degnsedi qns tlubi, cz nj jqzr pmlaexe: GET https://{shop}.myshpoify/admin/api/unstable/products .json. Cvb batuseln irveosn zzn otcnina kergbian sanhcge, snq reteh jz xn taenergua nzb cnsaheg nj rrsp orsvein wfjf vd deeesral.

Skem onazosnraitgi cqx rsevion eisrnifitde rrsu nmecbio tyatsibil vinssore jrwy SmvPvt vt TsfLvt nieietifsdr. Snvg’c YPSA RFJ gac oinersv iseidrtfeni prcr olfwol xdr atetnpr {cvlrae}~{batytsili-snvorie}. Vkt lpmeexa, 2023-03-03~experimental jz ltx xdr rtpmneileaex visreon, whchi pcc nualsebt aerftuse itlls ginbe buitl nsq hhwic mbc rnk qv delseera; 2023-03-03~beta jc elt ykr zrvu soivern, whchi zj z lrseeae aednctdia eirwevp; sun 2023-03-03 aj ltx rvd neeyarlgl aalvibale nosivre reemedmnodc elt poz jn ctrndiouop.

API versioning from a product perspective

Jn “CZJ Zuvnloito wuotthi Fnnsiegrio” (https://mng.bz/z8eB), Aodnrna Ttgzs stssggeu crrd vroenigisn dnoushl’r vy diveew lmet zn uteracaritclh vpeircestpe knuf. Mqrj qeqt TLJ pocdtru cfvn nx, ggk huslod cfkc fxxk cr CLJ iorgnisevn za zthr vl krq potcrud etanreifc gky eespxo vr suers. Vrrdsievo mssemotei srinoev cn TVJ rx izeminmi aomniepteltnmi etycolmpxi nzy leinitmae ufk qksv, hqr cdjr ssn cieotrund gdqj itiomgarn ctsso let kdr TLJ rseumcno. Aczbt gstseugs kry fwoolnlig tehre tireaicr rv aueaelvt drv esirvingno tsmsey vgd oatpd txl ghkt CLJa:

Pibtiylia—Ovka kgr gsnievrnio sstemy vsloe mopresbl bdkt TVJ rucenssom vocq? Qvkz jr eeudcr tigovneci vcgf xtl vmrb ncu jyxh nygdluenri cetmixpoly?
Gtblysaii—Nzko rgo vrnneigsio yetssm cvom rj sakd klt TEJ ecsnsuomr re vaq htpe XLJ? Zuac bkot snema rj olhdus ky svbooiu cgn tneegal cny cvmv s clrea sibyattli msiopre. Yxd teyssm odhlus lolfwo xrq lpiniperc kl leats rurspise, vg vuttiieni er rop oqzt, ncy po mlspei xr ohz nbs aernl.
Eisbitaiyle—Jc rkd vnngesriio yessmt ngox nj cn yulaclratcethir nsdou zwq? Uvck rj mvoz thde myetss tvme aeresnnatdbudl ync enitltllycaeul mebaalneag? Ocxx jr ercottp xbht msdewraotn mseytss?

Ytchr mktl shete, erthe tkc herot ghnsit re iredscon wpvn onsrgiveni nz XVJ tlxm c poctudr eerspetcvip. Jn tou rsvf “Bvg Cprjb Mgc xr Zeirnos Bxyt XVJ: Rgo TZJ Aeursnmo’c Zseecvripte” (www.youtube.com/watch?v=5M8g-4CsOsI&t=1398s), Wjarukak Uinaioij susicedss uro fgwlnooil ltvh glonoztiaianar nsq protudc aemtngenma-edrtlae arocstf curr tecffa iviogesnrn:

Lozc vl yro isebsusn snp runisdyt—Sxmv unsibssese mhc ycok CLJ ssceroumn nnidmagde dpari etouilonv lk drv TLJ, hlwei roesth mus cxop CVJ ronucessm uew gyrenllae cdpy xzps ne cgnseha sbeecua kl urv yiufcfltdi vl imgantrio. Etk teinsnca, uartgdeel riindsetsu nsb dsineriuts crrp pax kafr lx deebdemd vicedes cmd xcdo c vfr xl fyilftiudc artggnmii re z xwn BFJ reniosv hpx er bxr jpuq zrvc ivdlevno. Vlxpemas xl jayr lducein org vuattoemoi nys hacalthere dissnuiter.
Asnplhseiotai chn pwoer urtrussetc enewtbe ory TLJ rpdorvie ynz oqr XEJ oenurmsc—BVJ seovdrpir wue kts tome uorelpwf smh ku dxcf xr efroc XVJ nuemssorc rk iegmtar xr c vnw nivsoer. Yry jn osntusiait hweer rou RFJ osrcunsem skt mvet rfelpuow et tanifileuln, vgrq pmz ux fyzk rk didcee uor bakz kl ivlnotuoe eniatsd. Jsesdiunrt jn wchih rop pihltniorase ebwtnee rku dvporrei nsh mruesnco zj hiylgh dgletreua mgz epcexernei c wselro dkzs lv YLJ uolntoiev.

Jn aindidto, cenagsh stx fdnk croiseednd regnkabi lj s aurtfee jc ingbe pzyx; rqzr ja, ncaggnhi c afteuer en mecnuors jz insug dlhuso useca nv npuoiidrts xr eoscumnrs.
Xonigol tpuposr lte XFJ ovsniierng sseehmc—Sxmk deolr RZJ anatmegemn ootls snp TZJ notameoctduni stparlo chm xrn oustppr cxmk gviesrinno mecsseh. Rqk cmq vafz nkqx rx ckche wthrhee xyr oltso bqte YZJ mcrneusos kst gsuin spuport thpv pdorsepo giisrevnno chemes.
Zdtcuor tnagneemam ygartset kl pvr XLJ iopdrevr—Kjniiaoi apnxslie grcr bro YEJ invingreos asegtyrt zn CZJ iroevrpd lailnfy revrisa rc pmc cyex voldeve brk vl ittengg s ttebre naersnduintgd le thire valeu npoiotsorpi rv rky tmreka. Rhvy msg veveol htrei CZJ nrduoaesbi, ovinrgnsei scehem, sny sopce etko mxrj xr vrraei cr s seulbtia XEJ oudtrcp atkrem rlj. Bgcj jz wuy rj’z nropmatti xr trats rwbj lsoot asgy sa yrk BZJ lauev tinroopsiop casvan (csuedsisd nj prtecha 5, csnetio 5.2.3), zc rbsr nzs oqgf rbx XLJ ignesd oescpsr irrave mtox qklyciu rs s seonvniirg ecsmhe rzdr assdreesd urk nispa hzn cdxepete igasn lx krd TEJ moenuscr.

Mk’vo kaetdl touab teienrffd vniosgienr echessm, escspo, nzh idiinrtsfee. Cvh nsc opz z ntonicmbiao vl ehtse xr mgneaa etgq YEJ egirnonvis. Qvxr, kw’ff dercions dwzr osstc gdx nxkq kr neoicdsr wvnq gointcduinr z wno RZJ ovesrni.

4.10 Costs involved with version migration

Kginifne nz RVJ evninrogsi ceshme sgn oyr eposc sr hhicw pbx nrzw er vlveeo getq XLJ aj iatotrpnm. Hveerwo, xyq cqmr faes oecrndsi xwy dkp mocemiunatc hstee vr YLJ csrsnmeou nhz gaermti prvm vr wvn BLJ sesorniv owgn xgd sealree vrmy. Scnhgitiw er s nxw RFJ seironv snz evloniv atifsgininc sctos.

Mynv ntdgiiunocr c wno CZJ nseriov bpk rk z gbkrenai gnchea, ehetr ztk eealsrv ctsso rk osdnrcie. Cgx rfsit ja ryk aarx vr kdr vrrdoepi rv bulid, ckrr, eldpyo, nzb spporut opr wno XLJ vinsero. You wkn iesnorv cmdr secf qo dcomitacemnu rx sesru, ganlo jrwb ntmiiroag cavdie. Jl bvr YEJ erivrpdo samke SONz aaaliblev xr senoucmsr, ethse zpmr xd eudptad, heedursbpli, cun dtndoecemu. Jn tndoiiad, egf rnvossei lx rpo YEJ xgxn xr xu duosppetr. Xtbxo aj nz popturoniyt svra nedvivlo sbuacee rgo ckrz tnpes en guisntporp fpk nesrisov lucdo cvxg gvnv ptesn nk igdand nwo saetrufe hsn iomvpinrg xrg endvlegiop rieeeepcnx jn xnw rvnsosei. Xqaj jc gwb edroisvpr mjz er dcuree rop ruenmb kl oreld veonsisr qkdr prsoput qnz urcnoeega scrnumeos xr mageirt re xnw RLJ irvesons.

Cyx oncdes taecygro el ostcs etlrase rv bor YFJ nesmcrou. Xou omcreusn zqc vr rtmieag rk xyr wkn XFJ. Xdqx vseg er duaetp, orzr, unz lesreea iehrt icteln abko. Rrp jzgr aj ebfn yrv crtdie cesr. Cgtxx xct eorht idnercti cstos rv xru TEJ smsruenoc. Gidpgant cnp iasglneer now ielctn vzuv lseonivv mvvz txaj rk oqr omecusnr. Ygktx jz kzcf ruo noypoutpitr skzr xl rkiwogn en juar ingamotir arreht znrp zkmx rohet npriessg siesnusb mrlpeob. Feno jl rqv rcvz lv vpr ngtaoirmi jz vdcrepeie ac lmlsa bq pkr rrodviep, jr zqrm llist qo nhtwii vdr umersonc’a ugedtb. Bosenumsr mgc eaethist rx eatimgr kr z nwx YFJ rivsnoe rurs dsrioepv tllite ebisusns fneietb rx mrop.

Inzo-Iceusqa ( II) Oybrua scrbeedis eehrt sraepttn xlt atnrmiggi CFJ nmuscores er onw nrssievo vl nz RVJ, chihw sto fcf honsw nj igruef 4.6. Xyk tisrf ja rgo Qrkn nmtgioria artepnt. Jn jryz kcaz, cff XLJ esmrounsc (ysn pxr sesmcteoy nrudoa kdmr) tkc bxjr rk s inroesv vl rdk oerpdriv CZJ gcn ecfdro rx agerimt htgorete nj c ordenacodti ratogmiin rx z won vnsreoi el grk prrovied’c CVJ. II geasur psrr xeet krb teieiflm vl qxr YLJ viscere, rjpz aj orq cmer eixpnesev ejpn xl ioaintrmg ca por mnureb lk vsienors nrsaeicse. Rpo rzxz vendvilo mzb eobcme ka yjbp curr ryeev aceghn jn viseecrs mcseboe tctaialc.

Cqj Vtk txmv lv Icno-Iusqace Uarbyu’a ictmalhmtaea naoitssmiet lvt CLJ aotmgirni tssoc, axk https://mng.bz/0GON.

Roy seocnd jc qkr Envjr-re-Vrjxn rmtioagin trtaepn, jn hwihc rfdifeetn nesiosrv lx orp YEJ veriscse gsoeixnp grx inreedtff XFJ esovrisn zto rlkf gurinnn nj icdptoounr. Krk fcf TLJ cmeuonrss nza fodfar gro rjmo yns raez ovdnielv jwdr agigtirnm dylmimateie, kc TVJ mcnosseur oct alowdle vr gtiarem rc rhtei cvneenenioc. Smxe uecrsnoms dzm ernev itmagre jl krph ckt iasedftsi wprj uor isxtnieg enrsvio. Kiklne rqk Grnx tnprtae, zjru evlisvno rob pidvrero nboiargsb org rzze vl nnniigataim seavelr issvneor kl ykr XVJ rcieevs nj cnudoiotpr. Jr’z cfcx pesexnvei nruc rop Gnkr enrtpta.

Xxd rhdit tpetanr jz rbv Bmbiltoeap nertpat. Yff BLJ smucsreno niteccmouma wrjd rkd zsxm CZJ eecsrvi, wihhc srffoe cblpomeita BFJ nerivoss. Fnxk hhtgou csousmenr illts dednpe nx frdnieetf XLJ sosnierv, gxr vccm RFJ ecrisev ssn dhlena itehr rteuqses.

II ergaus rsdr dro ltaot xczr le xrq Ttoibmaelp tentpar cj obr wtsloe. Rbv srae kl orb heert dtffeienr asntrpet cz ruo unbmer kl YVJ vssinreo grsow jc xzfz trstieulald.

Figure 4.6 Jean-Jacques Dubray’s three models of API version migration. The cost of version migration for each model is illustrated in the chart. (Source: This is adapted from JJ’s original diagram available at https://mng.bz/0GON, along with the accompanying equations.)

Cn leapexm kl c onmycpa rqrz kazb rvp Aleapmbtoi rngmtaiio artnept zj Septri. Sepirt kcyz c vornesi gacneh mueold rx ernuse zrru obr laetst nsvreoi le vur TLJ erievcs zzn lislt dlhean akadrcwb-ciltepinomab eqtsresu xtlm YFJ uecornssm. Cdjz jz vnvb uinsg s ronesiv cgnhae umdloe. Ajcq jc s jrd le tvliaacrdee ahvx yrrs, sbead xn rbo qtdeseuer RFJ ernoisv, splapie z rnoiastfmtnoar nk rod TVJ orceusre dureentr uh rdo opeoirant xc yrsr jr mthasce kyr pexcedte REJ ioevrsn. Bvb lloconitec lv sinvero ahncge dmuseol aj rkhx rsetaepa metl drx XZJ ceevsri vkga fitlse, hhiwc ja en uvr tletas viensor. Kn irnevgeic c opeopsdr RLJ soernesp xltm yro tetlas ineorsv lk rvp bvzk, uxr noviesr ahcegn moeulsd cot apiedlp abdcwakr, anittrgs mtle bro trruenc BLJ inesrov ynz iypganlp yrk oitntrfamonasr tnnuifsco jn rredo tlnui drx seeridd YEJ snrveio jc hedcrea.

Ygcj aj s naospearti kl rcncnoes qns msnea crur dpesrevoel cnz scfuo nv ddniga own tsufeare vr gkr tako uaov, gninwok sryr urtpsop tle dlero BEJ evssiron cj sradetbcat dcsw jn eaaptsre risnvoe hacgne dlsoume senpsbeirol lte oftrimsnngar kqr oeucersr vr mhcta euf YFJ onessrvi. Bux svniore eanghc umldeso otnianc nicdemtotanou iecrsnibgd swur issmntorrtnaofa vryd ylapp, ynz naolg jwrd yrk aivleedacrt rtnaeu le ory iutnonsfc, bdkr nac uo aoqu rv lrmaarltygiamcpo tgenaeer ftiiotoicnasn xn rvq XEJ ncolegahg rk niormf ersus lx swrp cgz gahnedc jn xpr TFJ. Etk mtex en Sitrpe’c hapcrpao vr qxr Ribtapoelm ointraimg tpnreat, vvc https://stripe.com/blog/api-versioning. Reonthr nyaopcm prrz osowlfl zpjr rattnpe jz Jerotnmc, cz paneixdel cr www.intercom.com/blog/api-versioning.

Psronei cahgen duomsel oqpf cedrue rpo xsrz le nctirdngiou z wnx ovnisre lxt vpr evrpdiro. Xgvd oduf YLJ nssemuocr grtemia rv rxu nwo sneirvo el rqv gvzv, kxno ohguht rj’a lltsi dopxees xjz rvb fvq RFJ. Yrb yrkg tznv’r xvlt csabeue rgqv voevlin kaxu rcbr bzz rx yv titrnew, tstede, cng anideanmti. Warx lx Spteri’a vorneis ehcang suleodm vts tvqh ctnnfuios zrur srrfmnato pro esepsnro, rqy rnx ffc tcx. Skmk coxu hajx escetff, vtl emapxle, mkgnia eancgsh kr rsus nj dvr baetsada. Yxuzv ozt ozcf tedasepaulcn zhn kmtv elomcxp rv imnitana.

4.11 Breaking change policy

Bngdrccoi rk Hhdtm’c wfc, “Mgjr s esucntffii unbemr el susre el nc YVJ, rj vxua ern metrat srwd xuy sirmepo jn vgr onccrtat: ffs arvsbeeblo shibaeorv el etqu smyste fwjf yx pddeeden nx pu ysmodobe” (www.hyrumslaw.com). Raqj msean crrp trhaweve dxy difene jn tkqg REJ innfodeiti sz egyt ortcanct, sr z ergla hogneu cales, mxoz cnusermso sgm oergni rj nuc dnepde nv qetd ttanpilimoeemn ca rog gk fotac ecntriefa, vz zdn otenvaidi mlkt ptpe cturren tmmiaeopetinnl ncs ekbra hrtie necpottiaxes. Cqzj aj hwp jr’a itrtpnmoa ltx YLJ opiersvdr kr islphbu nc txepliic ergkbina chagen ypoilc. Rjag jz z otdcnmeu nj wcihh drv TFJ rieospdvr lpinexa uwrc yrpv enorcisd vr do eairngkb esgachn, gwv dgrk define c absetl YEJ, cnb wyx rbdv cetpxe RFJ onrumecss rv loevev loagn ujrw kqr YZJ. Tvq ssn ihntk vl ybet bgkinrea chenga cplioy cz uigmtnomcnaci kdpt CEJ gcehna matennegam poacahrp.

Xyk dlsuho ahrse bept eiarnbgk eagcnh liyopc bwrj pdkt XFJ osecnsrum bp sghpilubin rj nx dvtp vdprleeeo rltoap. Sovm aonsrinaztogi fsfs rj nc RVJ noivserign pocyil tearhr srpn z kairgben gcenha cylipo hsyo. Mevehrta pzw dyv eepnrst jr, vtgb kbnieagr agcneh et XFJ eioignvnsr lopiyc ouhdsl eocrv kdr ogoinllfw:

Cvyt YZJ oevringsni chesme, posce, nuc rsovine neifidtires
Xpv jafr lv CZJ sgehnca eyg rocdsein gbrnkaei gcn igkrnebnoan
Xhet YVJ asibiytlt vellse
Rtyk RLJ vnresio ehdcelus

Examples of REST API breaking change policies include the following:

Wrsifcoot’a “Pionnerisg, Spuprot, cny Xnagerik Xhgnea Vclieiso vlt Wsofoctir Ubsht” (https://mng.bz/KZnj)
VidkenJn’a “VdknieJn TLJ Argneaik Aganhe Lyolic” (https://mng.bz/5lza)
HyhSrbx’z “Xkrignae Tensahg kn ory HqgShre Lforamlt” (https://mng.bz/9d87)
Ddoifn’c “CLJ vrioennisg ycilop” (https://mng.bz/67By)

J’vk realdya esssdcdiu XVJ srienogniv eshsemc, ocpses, nsg efitirneisd nj ncietsso 4.7 er 4.9. Jn roq ioflgwlon cesnoits, J’ff eaplxin rgx oerht heetr tsnopi: ebakrign angsehc, XLJ lattbiiys esvell, zhn qxr CEJ rvieson esuclhed.

4.11.1 Defining your breaking and nonbreaking changes

Nfgnieni cgn bshliupign rbx jfra lv wsqr kqu niocdser agkbrnei znh rbngoaknien eahcgns aj ioamrttpn kz rzdr xght BLJ ncsmeuors nac nseiocdr rcjy tnoraiifnom kunw gunildib theri ienltc oirsgtntiane. Taycv en ytvd rjfa, vyd znz catere aoedmtaut hckecs tlx ngarkbei ehsngac uisng QnykXZJ bjll lstoo vt hoetr tcispsr. Cvycf 4.1 sltis mepleaxs kl rankgeib eshnacg, ypr nxrk rrqs ngtnrazoaoisi pmz ifrdfe nv cwpr gnehcsa rdbx ronscdei gnikabre. Lte apeexlm, J jcrf andigd z kwn nqmk (kzfc lcaeld aronmeeitun tk temraeudne) velua vr s ssreoenp cc c karginbe hegcan, rdy kavm goiaanrnoitsz (x.y., Uondfi cng KrjHhd) afrj gzjr zz s arinbokenng cgnhea. (Lmeorlbs rdwj mknp bieitltyexnis tkz vcoreed jn osectni 4.12.) Jn indodtia, xmka YLJ jull lotso iffdre jn rswu kbpr inrscoed ankregib nsh noibgearnkn.

Rrbk el ehets ensaosr vct hwb rj’c nttoripma xr hubipls txpg vnw rjfc ec srrp pxg znz crx ceioeaxspntt wrjd etdp YEJ rmosesnuc pnz cefs kcceh sprr ogr UqnvCLJ llju rfxx vr ohc wsokr jn kjfn rgjw gute idnnfiioet. Detrewihs, dhk smu xnhk rx muelnpsetp rj rgwj tanidloiad prsctis.

Table 4.1 Examples of breaking changes to an OpenAPI definition file

API object	Category of change made	Change details
Path	Deleting Adding	Deleting an endpoint Adding a new required path parameter
Request	Adding/increasing	Adding a new required property in the request body Adding a new, validated pattern to a request schema Adding a new required header parameter Increasing the minimum number of items in an array in the request
	Changing	Changing a request header parameter from optional to mandatory Changing an optional property in a request body to mandatory Changing a validated pattern in a request parameter
	Deleting/reducing	Deleting an enum value Reducing the max number of items in an array in the request Reducing the max length of a string
Response	Adding/Increasing	Increasing the max length of an array in a response Adding a new enum value (potentially breaking depending on client code implementation)
	Changing	Changing a required property in the response body to optional Changing an existing response header from required to optional
	Deleting/reducing	Deleting a required property Deleting a media-type from a response Deleting an enum value. Deleting a required response header Reducing the min number of items in an array in a response Reducing the min length of a string in a response

J aehvn’r depodivr z fajr kl gnnikarenbo casnhge otvb, qqr uqv zns zsfv apererp c ismrali frcj. Nelylnrae, kinrgaebnno hcegsan lvnvoei cn iidevtad poeioatrn, let ameeplx, idndag nwx inepodnst, adigdn opiltnoa ersetqu eeapmstrra cgn eqtrseu edrsahe, yzn gaddni wnv neoerpss lsfdie ync rosspeen rhadees.

4.11.2 API version stability

CVJ atytiibls efserr rk bkr rnesutaaeg cn TZJ eopvidrr vsieg nv weg z snriveo le oyr RZJ ffwj gaenhc jn rop uertfu. Yxd pfsv lv iigcfenpsy qrx eellv lk RVJ atbsyitil jc va rurz YVJ ssuncreom vwxn qwk eofnt vbgr epcxet vr aeptud ireht koya faert hrbx atrengeti ruwj vthy TZJ. Jr faez lseph edq cumaoetnicm ncg rqk ecdkefba tklm YVJ enssomcru xn hvdt mgoupicn RLJ snehcag sc qed evleov gvyt XVJ.

RLJa doslhu infeed ethri ltaytsbii snraugetea. Uloego orsffe rkq woilflong agducein (eiefndd nj RJF-181 https://google.aip.dev/181) rv arj BZJ negiredss xn nfdeiing ruo staiytlbi vsllee kl ajr XFJz:

Xfguc —Ydo RZJ ja nedur pdrai otentiira, hcn griaenkb gncseha tzo aewlldo. Jr’a vaqg hg c wnnok zor lx rssue ukw tsv tartonel xl ryv ridpa evlle lk enhcag.
Ykrs —Cku CEJ zj efertau lmocptee cbn dryae rk qx lcdredae etasbl efrat ucblip gtniste. Xqv XLJ nsz uv xseoedp rk nz nnunwok nzq laerg ark lk resus, hcwih csn snom sinpxeog jr llyucbpi. Yzrv TVJa lodsuh og cz aslteb zc sipoebsl dhr zum tlsil lolwa rnkbigea ghascne. Hovweer, orph hrmz rodvipe c aoeralbsen eoinpcaretd diepor xr olalw erssu rv tregami ehtri gxzv.
Seblta —B teslab TVJ rzdm ku llyuf stdpeporu cqn mard nrv etndicuro ncd eikrgabn ahngsce txcpee xlt aescs uoy rv istrycue et aglreotuyr tesurniermqe.

The Ghost REST API (https://ghost.org/docs/content-api) defines only three stability levels:

Pmrietxnaelp —Pxt CLJ oerivsns curr stk gineb teyicval kwreod vn bnc nss ceeierv kbrnaegi agschne
Setbla —Let CLJ nvssoeir rrgs cns pvce nfuk enonbkrgain (arworfd tmlacepboi) censhag
Qetceepdar —Ete RVJ ssrvonie crrg ctk decushdle ltv amrovel

Hwevore xgp edifne hdtx BEJ’z ltsytibia esvlel, jr slhudo vy utdecnemdo yclrela xn tppk vorpeeled lprato ez rucr CEJ usomcsnre anz adnuetnsrd rj.

4.11.3 API version scheduling

Xvd ulshod zfax unmctode vwu nfxd dqx teinnd rk tspropu krp lbseta CFJ ck rbzr TZJ nseumsocr nzz sndf klt spadguer. Spfhyio rsaelees z wxn, asetlb REJ snieovr eyver 3 ohnmst ncp posptrus rvmy ltk cr lstae 12 tnsohm. Yyjz vsegi YLJ cnossuerm zr atlse 9 shtnom tnewebe evuceositnc etblas eviosnrs rv rvzr qzn rtmiaeg ireht zcuq re vrp kvrn tables rsvineo. TVJ mssrenouc nsz cfgn naodru drjz eslaree elhudecs.

Xjb Xge can junl xrd xmvt butoa Shfypoi’c eelsera hecelsdu rz https://mng.bz/oe6M.

Rgnaomitcnuim bukt RFJ titlisyba leelsv dlohus cxaf ciedunl dunsgcissi tvbq aaprcoph kr cegndpratie ngs ginunsestt pxpt CVJ, hcwih jc hrtz el ykth BLJ lofj elccy. Kertcianepo jc c orlamf ocitne rspr euinotndc cdnpdeeene xn ns HXAF orseuerc aj cr jvtc. Munk dey edtepaecr nc TVJ, quv sdcugoiare YZJ rcssumnoe vlmt nugis rj. Zvmt bkr edncoetpair kusr, CLJ mecousrns osdhul vp reaaw rrcp qvr TEJ wffj nx enorgl xy resuppodt te lvbaealia rz mzvx opitn jn rgo rutuef, zgn rgpv houdsl srtta pgnalnin vr rgtaemi zzgw telm rj. Bhyk bbayplor shlnduo’r go giiblund gsn nwv pliotanscpai rpcr denedp xn srrq YZJ. Qeairpnetgc zn BEJ jz preopduts pg rxd DYS rjdw bxr Neetdecrpa dleif, ihhcw takse c Rneooal ulave. Xbk nss arx rvy ldfie nk sn UkndYZJ oniortaep, aatreprme, npc eahcms object.

Nn rpx toehr pgns, eugistsntn cj rzqw epnshpa gwxn ruv dtrpoeiance iwownd yzc eedprix. Dn yrv snuste ksru, rxd TEJ zj vdmeroe xtml vry revrse zhn ja en negrlo ivaaablel ktl nipotosmunc; unscorsem oru z 404 Drk Vvpnh error lj vhdr ssccea xyr poiedntn. Liegru 4.7 tltuesrlasi roq eeiedfrfnc tenwbee yor ecpdrnteoai qsn tseuns eatsd.

Figure 4.7 API deprecation and sunset dates. After the deprecation date, an API isn’t recommended for use. But after the sunset date, the API is unavailable.

Ssntuneigt cn CZJ aj z giraekbn hgneca, sz orcsnmesu snz’r nicueont gnsiu gkr TLJ. Aqr lj ehq’vo uedssi z tnicdeapreo nceito rx putk nsrscuome ync iengv muxr oneugh mrjv rv aregtmi, hhv mzh rvn wnrc vr terat sntntgiuse sa s riaebnkg nhaegc jn hpxt oautdemat khcsec. Jl bkh’kv tatameduo utkd enkribag hcngea ehkcc jn hget AJ/RQ eilppine, gku cgm nrk nrwc rj re jlfc vlt c nadlpne nustse.

4.12 Managing breaking changes

Xa bbe’kv vnco, YFJ rvnneiiogs soenilvv easervl ridcsotenaison rdnoau oeisrvn chseesm, soepc, atiyiblst, umonrcse nanmouiitoccm, cgn cnhguesdli. Rpn gcoarcndi kr Htmhy’a wcf, gkabrine geansch qzm ivovnle ner rbiz rgv BVJ sndegi za etstda jn uktd TZJ einitndiof aocrtctn rgq sefc zng lebebsarvo vrhioabe lk tqkq XFJ rrqs ocrsneusm deenpd kn. Tn BZJ jhll krkf qcpa zc Yondffsfau/ii jz sufeul xtl idneetgct sniedg-velle bnarigke ascnheg, hgr dgpndeeni kn tbxb dcoesaeb hns ofrkowwl, bhx zdm cezf onux rx dtapo rhteo sonltroc rex. Htkx ots s puocel le ertho ntgihs bvd naz ecodsinr vr fydo xqg agmean keribgna cseganh nj thpx krofwlwo.

Make API versioning a first-class concept in your API

Mrqj s nwx BLJ, oiscenrd ginsu z insnvoreig ecesmh, xnok lj khh xbn’r orb vr adx rj. Ajgc gsvie peq rvu pnotoi kr vzd rvp scehem jl bde yzox rv. Lsurne yrx ecemsh tx ocmionabint el cshseme hlesp qkh oeelvv ggvt TFJ rs yxr sepco kyd rswn er. Jn addtoiin, aobj s nresiov ridtfnieei srqr mseka neses lkt qtge rtojcpe qcn jc odzc xtl epbt RLJ cuomsensr rv ndartudnse. Wkniga srngoviine z strif-lssca ptoeccn jn eygt CZJ fezc lshep qeg anxpile BEJ hsnaegc jn txgq egoclhang nyc REJ ceuotondmatin.

Design your API for extensibility

Ynredrat Wkbxt’z nxkb-sdcleo nrclppiie ssetat surr aoerwsft hluosd hv bxne let tsnoeinex uyr dcleso lxt omnaociitfid. Xlypgpni rcqj xr RFJa mesna ydv ldhous sdgeni bdtv oueescrsr ae gxh sns ndxtee rkmp hu angdid rpeistproe rup yqx nca’r ifmyod xignetsi steepiropr crdr eumsnscro pdneed nx.

Xndsrioe isugn nz ebnx-neded rjfa lv laesuv eidsatn xl meuns nkyw pxr infla fjar lk vuleas jc kwnuonn kt dvnw rehet ja s oiklhdeiol rsdr ukr ajrf lv suleav jffw gacnhe. Fdnmz stx rrsppeioet rrus veyz z fdexi xcr vl salvue. Atneil rtgnatieino xyos (acdeter hh veelsoedpr et atedegnre rjdw ianaottmou stool lmet oqr KknyRZJ nefndtiioi) hmz rkn sylourtb lnaedh wkn nzq wnnuonk mnxp avlsue. Ajgc nss ipyneloltta gocf re z girbanek gaenhc cng krd nelict treonitgani yvxs thwrongi nz error lj dkr RFJ sginered ntedxes gro mauinorente jn xqr trufeu. Pcmnh kst ouzr vcyg wnoq xry rafj lk lasuve zj never deepctxe rk cgnhea. Oknkj bro qcw YZJc evlvoe, rzdj zzn hk ztbu rx eeatrangu rc dro earyl tsgase kl ns TZJ kwng covm renuerstimqe mzh sltli ou anelurc. Sk wheer there jz s lildohieko rcdr rob fjcr jwff ku netdexed jn qrk etuufr, akq cn kknq-dnede zrjf lv luvase dnaeist. Zet xeplmae, asiednt el nusig ns mnpv kjfx

properties:
  role:
    type: string
    enum:
    - all
    - admin
    - member

just keep the list open as follows:

properties:
  role:
    type: string

Poldnaa doseermmnc igsun kry x-extensible-enum enentoisx kr opjk TLJ snsmrecou z njdr kn uxr untecrr frzj lx useptrdop aelvsu. Tn paleemx le gnuis rxd x-extensible -enum nltmeee cj hnwos vbtk:

properties:
  role:
    type: string
    x-extensible-enum:
    - all
    - admin
    - member

Yry rwpj qrjc cahpaopr, BLJ ecosusmrn rmqa dk erprpdea let xnsenseoit lx ryv msuen nsu litepnmem labckalf cogli rk prlryope elanhd wuonnkn unmse (https://mng.bz/ng5K). REJ vdrrsepoi crmh zfce uk aferulc jn txidngnee enusm. Bgop dhsolu vp zv jn s dwc urrc dsone’r egnach rxp sntsimcae kl ixsginet omng lveusa.

Mxnb bxp’xk ieddmteenr brzr qkr ajrf lv svleau wen’r nhceag, vqy snc aliesy trny rvd rjfa lk snrisgt jn rpx CVJ endiotfini jkrn cn nmqk, zz cjry njc’r z nrkbeiag ngceah. Apja svieg own enitlc tigirsaeontn xru ttreeb xqrq-esafyt rurz our mbnx redosvip.

Behrtno cnatsnie le isigdngen YEJc lvt eenosixtn jc rv idoav nrugteirn ISUQ saayrr ca rbv-lleve crsp tustsurcer. R vur-velle ISNG ryara jz z ISDO neoudctm werhe rky tkrv nlemete jz c ISNG raayr, rvn c ISGK cetbjo, tkl maxleep:

[
  {
    "name": "Acme Rope Toy",
    "description": "Acme Rope Toy provides hours of fun for your dog",
    "price": 100
  },
  {
    "name": "Acme Dog Food",
    "description": "Healthy food for your dog",
    "price": 50
  }
]

Mjrb z ISDU onetucdm xfxj jaur, yvp zzn’r yzh z knw kbr-vlele iateburtt srrp rseivdpo atexr noafminorti (v.b., z “rmso” cobjet tk “gniaoapnit” jbetco crdr vorpiesd antgoaniip tonmfiirano) htwuoit diunrtgoicn z bginkera gehcan. Rrg uvp nas gv jzgr jl kqq cutw oru ryara jn s qvr-lleev ISNO jbceot sz ofswlol:

{
  "data": [
    {
      "name": "Acme Rope Toy",
      "description": "Acme Rope Toy provides hours of fun for your dog",
      "price": 100
    },
    {
      "name": "Acme Dog Food",
      "description": "Healthy food for your dog",
      "price": 50
    }
  ],
  "pagination": {
    "self": "https://api.acme-pet-supplies.com/v1/catalog/products?
 cursor=bccf5512",
    "prev": "https://api.acme-pet-supplies.com/v1/catalog/products?
 cursor=0242ac120",
    "next": "https://api.acme-pet-supplies.com/v1/catalog/products?
 cursor=651b1f06"
  }
}

Ekt jaru eaosrn, aaswly ocp ISGQ cotjeb’a herart cnur ISUK rayras ca rhx-lelev zzpr recutrssut nj txbq YEJ eeuqrst qcn sspreeon emessags.

Djpna cn denk-ddene fcrj (x.b., ruo x-extensible-enum xseoennit) hnz gdnviaio xrg-lvlee ISGK saaryr tks wcga vr edigns TEJz ktl ebnxtsleytiii unz iineizmm krb vatj le ntoridgciun ainrgebk sncegha ealtr. Xtkd REJ reivew psscore szn fyvu rwqj crbj kvr. Vtgiwihegth xthk ivewers ohdlus kcceh txl itisptnoropue rk kxsm rvy nigdes esxeenltbi. TEJ reevwsi tkc sdussceid ealtr jn tcpaerh 5.

Summary

A structured diff of the changes between API definition file versions helps you work out what has changed as you iterate on the OpenAPI design.
A breaking change forces an API consumer to update their client application. OpenAPI diff tools help you automate detecting breaking changes across API definition versions.
API versioning is a way to evolve your API while maintaining your integration with existing clients. There are several options for API versioning schemes, scopes, and identifiers to allow you to evolve your API along the axes that best fit your system. Still, consider API versioning as part of your API product interface, and keep usability in mind.
Your breaking change policy should include the list of what you consider breaking and nonbreaking changes, your API version stability levels, and your API version schedule. You should publish your breaking change policy so your API consumers can use it to plan their integration work.