REST API versioning

[Robson de Almeida]

Boa tarde senhores,

Estamos desenvolvendo uma API RESTfull.

E eu gostaria de ouvir a opinião de vocês a respeito do versionamento de APIs deste estilo.

Li alguns materiais sobre o assunto e parece haver duas abordagens que dividem a comunidade:

• a primeira seria colocar a versão no URI, por exemplo: /api/v1/customers
• a segunda propõe utilizar de um Header customizado, por exemplo: X-Some-Api: v1

Como desenvolvedores da API, por qual solição a princípio vocês optariam?

E como clientes da API, o que vocês acham melhor?

Abs.

[Diogo Lucas]

Cara, minha sugestão é olhar o que diz o mercado: as grandes APIs (Google, Twitter, Amazon, etc) lidam como com versionamento? Afinal, usabilidade é um critério importante para uma API e seguir o padrão de mercado ajuda nisso.

Esse cara aqui fez o levantamento:

Versioning strategies in popular REST APIs

API NAME	VERSIONING	EXAMPLE
Twillo	date in URI
Twitter	URI
Atlassian	URI
Google Search	URI
Github API	URI
Azure	Custom Header	x-ms-version: 2011-08-18
Facebook	No versioning (changed URI from api.facebook.com to graph.facebook.com though)?
Bing Maps	URI
Google maps	unknown/strange
Netflix	URI parameter	http://api.netflix.com/catalog/titles/series/70023522?v=1.5
Salesforce	URI with version introspection	{ “label”:”Winter ’10″ “version”:”20.0″, “url”:”/services/data/v20.0″, }
Google data API (youtube/spreadsheets/others)	URI parameter or custom header	“GData-Version: X.0″ or “v=X.0″
Flickr	No versioning?
Digg	URI	http://services.digg.com/2.0/comment.bury
Delicious	URI	https://api.del.icio.us/v1/posts/update
Last FM	URI	http://ws.audioscrobbler.com/2.0/
LinkedIn	URI	http://api.linkedin.com/v1/people/~/connections
Foursquare	URI	https://api.foursquare.com/v2/venues/40a55d80f964a52020f31ee3?oauth_token=XXX&v=YYYYMMDD
Freebase	URI	https://www.googleapis.com/freebase/v1/search?query=nirvana&indent=true
paypal	parameter	&VERSION=XX.0
Twitpic	URI	http://api.twitpic.com/2/upload.format
Etsy	URI	http://openapi.etsy.com/v2
Tropo	URI	https://api.tropo.com/1.0/sessions
Tumblr	URI	api.tumblr.com/v2/user/
openstreetmap	URI and response body	http://server/api/0.6/changeset/create
Ebay	URI (I think)	http://open.api.ebay.com/shopping?version=713
Reddit	No versioning?
Groupon	URI	http://api.groupon.com/v2/channels//deals{.json|.xml}
Geonames
Wikipedia	no versioning I think?
Bitly	URI	https://api-ssl.bitly.com/v3/shorten
Disqus	URI	https://disqus.com/api/3.0/posts/remove.json
Yammer	URI	/api/v1
Drop Box	URI	https://api.dropbox.com/1/oauth/request_token
Amazon Simple Queue Service (Soap)	URI Parameter and WSDL URI	&Version=2011-10-01

Dei uma olhada rápida na documentação das APIs do Google e do Twitter e bateu com o que ele falou.

[]s

Diogo

PS: francamente, acho que não inventando demais agora podes te preocupar com versionamento só quando ele for necessário. Fazer uma API bem feita é f*, considerando os vários requisitos envolvidos (usabilidade, abstração, estabilidade, escalabilidade, segurança...) e provavelmente vale mais a pena queimar neurônio em outras partes dela...

2013/2/1 Robson de Almeida <obiua...@gmail.com>

--
--
--
Acesse nosso blog http://devrs.net/
Siga-nos no twitter! http://twitter.com/DevRsNet
--
Antes de criar um novo post, para maior organização do grupo, procure seguir as regras de TAGS: http://devrs.net/regras-da-lista
Para postar para o grupo, envie email para de...@googlegroups.com
Para sair do grupo, envie email para devrs+un...@googlegroups.com
 
---
Você está recebendo esta mensagem porque se inscreveu no grupo "DevRS.NET" dos Grupos do Google.
Para cancelar a inscrição neste grupo e parar de receber seus e-mails, envie um e-mail para devrs+un...@googlegroups.com.
Para obter mais opções, acesse https://groups.google.com/groups/opt_out.
 
 

[Gustavo N. Reis]

A primeira opção é a mais tri! (pensando como cliente da API)

/api/v1/customers

2013/2/1 Robson de Almeida <obiua...@gmail.com>

Boa tarde senhores,

--

--
--
Acesse nosso blog http://devrs.net/
Siga-nos no twitter! http://twitter.com/DevRsNet
--
Antes de criar um novo post, para maior organização do grupo, procure seguir as regras de TAGS: http://devrs.net/regras-da-lista
Para postar para o grupo, envie email para de...@googlegroups.com
Para sair do grupo, envie email para devrs+un...@googlegroups.com
 
---
Você está recebendo esta mensagem porque se inscreveu no grupo "DevRS.NET" dos Grupos do Google.
Para cancelar a inscrição neste grupo e parar de receber seus e-mails, envie um e-mail para devrs+un...@googlegroups.com.
Para obter mais opções, acesse https://groups.google.com/groups/opt_out.
 
 

--

---

Gustavo N. Reis

(51) 8112-4551

[Robson de Almeida]

@Diogo, obrigado pela opinião e pelo material.

@Gustavo, obrigado pela opinião.

Robson de Almeida
Developer and aspiring entrepreneur
@robsondealmeida | robsondealmeida.org

Create your free signature: CLICK HERE!

2013/2/1 Gustavo N. Reis <gustav...@gmail.com>