12 - Versionamento da API Antes de liberar sua API REST, consi | Curso de design de APIs REST

12 - Versionamento da API
Antes de liberar sua API REST, considere também como lidar com o controle de versão, porque você não pode garantir que todos os seus usuários sempre usarão a versão mais recente da API.

Por exemplo, imagine que você publicou um aplicativo na loja de aplicativos com uma API (v1). Na próxima versão da sua API (v2), que será usada em seu site, você alterou uma das chamadas de URI e o formato de resposta. Portanto, se você não oferecer suporte a versões, seu aplicativo falhará até você atualizar seu aplicativo com a nova versão da API.

Agora que você sabe o motivo por trás do controle de versão, vamos ver como isso deve ser feito.
A maneira mais comum de criar uma versão de uma API é incluir o número da versão em cada URL. Por exemplo:

http://api.example.com/v1/users/
http://api.example.com/v2.1/users/{id}/projects/{id}/run

Desta forma, a estrutura e a versão estão corretas no URI, e é simples de usar.

A outra abordagem é incluir a versão no cabeçalho HTTP. Se você usar essa abordagem, ainda poderá manipular a solicitação em que a versão está ausente e não está visível no próprio URI.

Nota: Existem outros tipos de abordagens em que o controle de versão é opcional e, se uma versão não for especificada, ela obterá automaticamente a versão mais recente. A desvantagem dessas abordagens é que os desenvolvedores devem agir imediatamente para atualizar os aplicativos, a fim de não quebrar a experiência.

Outra maneira de atualizar sua API é manipular cada plataforma separadamente. Digamos que você tenha aplicativos para Android, iOS e Web, e eles se comportam de maneira diferente. Você pode criar versões diferentes para sua API para otimizar cada plataforma separadamente:

http://api.example.com/a-v5/codes/{id}
http://api.example.com/i-v4/codes/{id}
http://api.example.com/w-v16/codes/{id}

Nota: O gerenciamento de plataformas geralmente é tratado usando os cabeçalhos HTTP.