Re: API versioning
Cristian Costantini <[email protected]> Sat, 22 Feb 2014 16:05:04 +0100
| Newsgroups | gmane.comp.cms.cold-fusion.devel.italian |
|---|---|
| Message-ID | <[email protected]> |
--Apple-Mail-12-309960427
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain;
charset=windows-1252
Ciao Luca,
personalmente uso questo metodo=20
V 1.0 Prima versione
V 2.0 depreco la V 1.0
V 3.0 depreco la v 2.0 ed elimino la V 1.0
e cos=EC via...
do al client il tempo di fare le modifiche necessarie per non avere disserv=
izi.
In pratica il client pu=F2 usare le interfacce della V1.0 sulle API V2.0 ma=
non le potr=E0 usare dalla V3.0
Ho avuto una brutta esperienza con ZenDesk che =E8 passato dalla V1.0 alla =
V2.0 (stravolgendo interfacce e strutture dati) senza avere una versione di=
"mezzo" per fare le modifiche con conseguenze non piacevoli.
per la URL delle API seguo questa logica
https://api.dominio.ext/V1.0/method/param1/param2/...
La folder V1.0 =E8 un context dove girano i servizi REST
Io preferisco questa logica perch=E9 mi permette di passare da una API V1.0=
a V2.0 senza tanti problemi
Nei messaggi di ritorno delle chiamate API deprecate, ritorno un codice per=
avvisare il client. In questo modo posso notificare alle mie App di aggior=
nare la versione.
Sempre a mio parere non userei mai una versione major come default perch=E9=
mi impone di modificare il client senza avere il tempo necessario per aggi=
ornare tutto creando dei disservizi ai client.
Cristian
Il giorno 22/feb/2014, alle ore 13.16, Luca Bianchi ha scritto:
> Ciao lista,
> Mi trovo a dover versionare delle API, in modo da poter supportare client=
che abbiano un tempo di migrazione abbastanza lento: rilascio delle API in=
beta, rilascio pubblico, deprecation delle vecchie, ritiro delle vecchie.
>=20
> Ho definito una policy di questo tipo per i rilasci:
> - major release: retrocompatibilit=E1 non garantita, le signature possono=
cambiare cos=EC come le interfacce
> - minor release: le interfacce non cambiano, possono solo essere aggiunte=
nuove API, il comportamento interno pu=F2 cambiare di molto (es. uso un'al=
goritmo pi=F9 preciso)=20
> - refresh release: sono bug fix e small improvement, i client possono anc=
he ignorarle, nulla cambia
>=20
> Il tema per=F2 =E9 capire qual'=E9 il modo migliore.=20
> Che io sappia ci sono 3 possibilit=E0:
> - url component es. http://www.mioservizio.com/rest/2/my/great/api
> In questo caso propenderei per mettere nella url component solo la major =
version
> - header http: in questo caso diventa anche scomodo via il test manuale. =
Posso per=F2 fissare il default all'ultima versione supportata, etc.
> - query string: questa =E9 quella che mi piace meno=20
>=20
> Cosa consigliate?
>=20
> Inviato da iPad
>=20
>=20
--Apple-Mail-12-309960427
Content-Type: text/html; charset=windows-1252
Content-Transfer-Encoding: quoted-printable
<head>
<style type=3D"text/css">
<!--
/* start of attachment style */
.ygrp-photo-title{
clear: both;
font-size: smaller;
height: 15px;
overflow: hidden;
text-align: center;
width: 75px;
}
div.ygrp-photo{
background-position: center;
background-repeat: no-repeat;
background-color: white;
border: 1px solid black;
height: 62px;
width: 62px;
}
div.photo-title=20
a,
div.photo-title a:active,
div.photo-title a:hover,
div.photo-title a:visited {
text-decoration: none;=20
}
div.attach-table div.attach-row {
clear: both;
}
div.attach-table div.attach-row div {
float: left;
/* margin: 2px;*/
}
p {
clear: both;
padding: 15px 0 3px 0;
overflow: hidden;
}
div.ygrp-file {
width: 30px;
valign: middle;
}
div.attach-table div.attach-row div div a {
text-decoration: none;
}
div.attach-table div.attach-row div div span {
font-weight: normal;
}
div.ygrp-file-title {
font-weight: bold;
}
/* end of attachment style */
-->
</style>
</head>
<html><head></head><body style=3D"word-wrap: break-word; -webkit-nbsp-mode:=
space; -webkit-line-break: after-white-space; ">
<!-- |**|begin egp html banner|**| -->
<br><br>
<!-- |**|end egp html banner|**| -->
Ciao Luca,<div><br></div><div>personalmente uso questo metodo </div><d=
iv><br></div><div>V 1.0 Prima versione</div><div><br></div><div>V 2.0 depre=
co la V 1.0</div><div><br></div><div>V 3.0 depreco la v 2.0 ed elimino la V=
1.0</div><div><br></div><div>e cos=EC via...</div><div><br></div><div>do a=
l client il tempo di fare le modifiche necessarie per non avere disservizi.=
</div><div>In pratica il client pu=F2 usare le interfacce della V1.0 sulle =
API V2.0 ma non le potr=E0 usare dalla V3.0</div><div>Ho avuto una brutta e=
sperienza con ZenDesk che =E8 passato dalla V1.0 alla V2.0 (stravolgendo in=
terfacce e strutture dati) senza avere una versione di "mezzo" per fare le =
modifiche con conseguenze non piacevoli.</div><div><br></div><div>per la UR=
L delle API seguo questa logica</div><div><br></div><div><a href=3D"https:/=
/api.dominio.ext/V1.0/method/param1/param2/">https://api.dominio.ext/V1.0/m=
ethod/param1/param2/</a>...</div><div><br></div><div>La folder V1.0 =E8 un =
context dove girano i servizi REST</div><div>Io preferisco questa logica pe=
rch=E9 mi permette di passare da una API V1.0 a V2.0 senza tanti problemi</=
div><div><br></div><div>Nei messaggi di ritorno delle chiamate API deprecat=
e, ritorno un codice per avvisare il client. In questo modo posso notificar=
e alle mie App di aggiornare la versione.</div><div><br></div><div>Sempre a=
mio parere non userei mai una versione major come default perch=E9 mi impo=
ne di modificare il client senza avere il tempo necessario per aggiornare t=
utto creando dei disservizi ai client.</div><div><br></div><div>Cristian</d=
iv><div><br>
<br><div><div>Il giorno 22/feb/2014, alle ore 13.16, Luca Bianchi ha scritt=
o:</div><br class=3D"Apple-interchange-newline"><blockquote type=3D"cite">
=20
<div style=3D"background-color: rgb(255, 255, 255); position: static; z-ind=
ex: auto; ">
<span style=3D"display:none"> </span>
<div id=3D"ygrp-text"><p>Ciao lista,<br>
Mi trovo a dover versionare delle API, in modo da poter supportare client c=
he abbiano un tempo di migrazione abbastanza lento: rilascio delle API in b=
eta, rilascio pubblico, deprecation delle vecchie, ritiro delle vecchie.<br=
>
<br>
Ho definito una policy di questo tipo per i rilasci:<br>
- major release: retrocompatibilit=E1 non garantita, le signature possono c=
ambiare cos=EC come le interfacce<br>
- minor release: le interfacce non cambiano, possono solo essere aggiunte n=
uove API, il comportamento interno pu=F2 cambiare di molto (es. uso un'algo=
ritmo pi=F9 preciso) <br>
- refresh release: sono bug fix e small improvement, i client possono anche=
ignorarle, nulla cambia<br>
<br>
Il tema per=F2 =E9 capire qual'=E9 il modo migliore. <br>
Che io sappia ci sono 3 possibilit=E0:<br>
- url component es. <a href=3D"http://www.mioservizio.com/rest/2/my/great/a=
pi">http://www.mioservizio.com/rest/2/my/great/api</a><br>
In questo caso propenderei per mettere nella url component solo la major ve=
rsion<br>
- header http: in questo caso diventa anche scomodo via il test manuale. Po=
sso per=F2 fissare il default all'ultima versione supportata, etc.<br>
- query string: questa =E9 quella che mi piace meno <br>
<br>
Cosa consigliate?<br>
<br>
Inviato da iPad</p>
</div>
=20=20=20=20=20
=20=20=20=20
</div>
<!-- end group email -->
</blockquote></div><br></div>
<!-- |**|begin egp html banner|**| -->
<br>
<br>
<!-- |**|end egp html banner|**| -->
<div width=3D"1" style=3D"color: white; clear: both;"/>__._,_.___</div>
=20=20=20=20=20=20
=20=20=20=20=20=20
<!-- Start Recommendations -->
<!-- End Recommendations -->
<!-- |**|begin egp html banner|**| -->
<br><br>
<tt>
CFMentor<BR>
<a href=3D"http://www.cfmentor.com">http://www.cfmentor.com</a></tt>
<br><br>
<!-- |**|end egp html banner|**| -->
<!-- |**|begin egp html banner|**| -->
<img src=3D"http://geo.yahoo.com/serv?s=3D97490485/grpId=3D170861/grpspId=
=3D559000199/msgId=3D41888/stime=3D1393081514" width=3D"1" height=3D"1"> <b=
r>
<!-- |**|end egp html banner|**| -->
=20=20=20=20
<!-- |**|begin egp html banner|**| -->
<br>
=20=20=20
=20=20=20=20=20
=20
<!-- |**|begin egp html banner|**| -->
<div id=3D"ygrp-vital" style=3D"background-color: #f2f2f2; font-fam=
ily: Verdana; font-size: 10px; margin-bottom: 10px; padding: 10px;">
<span id=3D"vithd" style=3D"font-weight: bold; color: #333; text-tr=
ansform: uppercase; "><a href=3D"http://it.groups.yahoo.com/group/cfmentor;=
_ylc=3DX3oDMTJjcXNiajBsBF9TAzk3NDkwNDg3BGdycElkAzE3MDg2MQRncnBzcElkAzU1OTAw=
MDE5OQRzZWMDdnRsBHNsawN2Z2hwBHN0aW1lAzEzOTMwODE1MTQ-" style=3D"text-decorat=
ion: none;">Visita il tuo gruppo</a></span>
<ul style=3D"list-style-type: none; margin: 0; padding: 0; display: in=
line;">
</ul>
</div>
<div id=3D"ft" style=3D"font-family: Arial; font-size: 11px; margin-top: 5p=
x; padding: 0 2px 0 0; clear: both;">
<a href=3D"http://it.groups.yahoo.com/;_ylc=3DX3oDMTJidmRlNmt2BF9TAzk3NDk=
wNDg1BGdycElkAzE3MDg2MQRncnBzcElkAzU1OTAwMDE5OQRzZWMDZnRyBHNsawNnZnAEc3RpbW=
UDMTM5MzA4MTUxNA--" style=3D"float: left;"><img src=3D"http://l.yimg.com/ru=
/static/images/yg/img/email/new_logo/yahoo_groups_it-IT_135x19.png" height=
=3D"19" width=3D"<? ol var!Pref.EmailFooterLogo.FullFeatured.Width ?>" alt=
=3D"Yahoo! Gruppi" style=3D"border: 0;"/></a>
<div style=3D"color: #747575; float: right;"> • <a href=3D"http://in=
fo.yahoo.com/privacy/it/yahoo/groups/details.html" style=3D"text-decoration=
: none;">Privacy</a> • <a href=3D"mailto:cfmentor-unsubscribe@yahoogro=
ups.com?subject=3DAnnulla iscrizione" style=3D"text-decoration: none;">Annu=
lla iscrizione</a> • <a href=3D"http://info.yahoo.com/legal/it/yahoo/t=
os.html" style=3D"text-decoration: none;">Condizioni generali di utilizzo d=
el servizio</a> </div>
</div>
<!-- |**|end egp html banner|**| -->
</div> <!-- ygrp-msg -->
=20=20=20
<br>
<!-- |**|end egp html banner|**| -->
<div style=3D"color: white; clear: both;"/>__,_._,___</div>
</body></html>
--Apple-Mail-12-309960427--