...
- Alterando-se a minorVersion da mensagem padronizada, deve-se alterar a minorVersion da API.
- Alterando-se a majorVersion da mensagem padronizada, deve-se alterar a majorVersion da API.
- Inclusão de verbos HTTP, ações ou filtros na API não alteram versão.
- Alteração de comportamento de endpoint ou na forma de passar os parâmetros alteram versão da API, entretanto não é necessário replicar todos os outros endpoints da API para a nova versão.
Exemplos de versionamento
Para tornar mais claro como versionar as APIs baseadas em mensagem padronizada, colocaremos a seguir um caso de uso.
- Mensagem padronizada Request, utilizada para CRUD de requisições de estoque ou compras.
- Mensagem padronizada CancelRequest, utilizada para cancelamento de requisições.
Na versão inicial da API temos os seguintes endpoints, todos baseados na versão 1.000 da transação Request:
| Bloco de código |
|---|
|
GET /api/manufacturing/stock/v1/requests
GET /api/manufacturing/stock/v1/requests/{requestId}
POST /api/manufacturing/stock/v1/requests
PUT /api/manufacturing/stock/v1/requests/{requestId}
DELETE /api/manufacturing/stock/v1/requests/{requestId} |
Em um momento posterior, foi liberada a operação de cancelamento da requisição, utilizando a transação CancelRequest, versão 1.000, conforme abaixo:
| Bloco de código |
|---|
| title | Novo Endpoint na API v1 |
|---|
|
POST /api/manufacturing/stock/v1/requests/{requestId}/cancelRequest |
A API teve mais um endpoint adicionado, porém os demais endpoints não tiveram alteração de contrato. Neste caso, a versão do novo endpoint permanece igual a dos demais.
Consideremos agora, que a API teve alteração na versão da transação Request, evoluindo para a versão 1.001. Neste caso, devemos alterar a versão da API, modificando o minorVersion, conforme segue:
| Bloco de código |
|---|
|
GET /api/manufacturing/stock/v1.1/requests
GET /api/manufacturing/stock/v1.1/requests/{requestId}
POST /api/manufacturing/stock/v1.1/requests
PUT /api/manufacturing/stock/v1.1/requests/{requestId}
DELETE /api/manufacturing/stock/v1.1/requests/{requestId} |
Agora, teremos disponíveis os seguintes endpoints (observe que o endpoint de cancelamento permaneceu na v1):
| Bloco de código |
|---|
| title | Endpoints disponíveis |
|---|
|
- V1
GET /api/manufacturing/stock/v1/requests
GET /api/manufacturing/stock/v1/requests/{requestId}
POST /api/manufacturing/stock/v1/requests
PUT /api/manufacturing/stock/v1/requests/{requestId}
DELETE /api/manufacturing/stock/v1/requests/{requestId}
POST /api/manufacturing/stock/v1/requests/{requestId}/cancelRequest
- V1.1
GET /api/manufacturing/stock/v1.1/requests
GET /api/manufacturing/stock/v1.1/requests/{requestId}
POST /api/manufacturing/stock/v1.1/requests
PUT /api/manufacturing/stock/v1.1/requests/{requestId}
DELETE /api/manufacturing/stock/v1.1/requests/{requestId} |
Seguindo com o nosso exemplo, vamos considerar agora, que o endpoint de cancelamento precisa, obrigatoriamente, receber um parâmetro de query. Isso altera consideravelmente o comportamento do endpoint. Sendo assim, o incremento deve ocorrer na majorVersion do endpoint, conforme segue.
| Bloco de código |
|---|
|
POST /api/manufacturing/stock/v2/request/{requestId}/cancelRequest?mandatoryParam=someValue |
Com isso, teremos o seguinte cenário de APIs:
| Bloco de código |
|---|
| title | Endpoints disponíveis |
|---|
|
- v1
GET /api/manufacturing/stock/v1/requests
GET /api/manufacturing/stock/v1/requests/{requestId}
POST /api/manufacturing/stock/v1/requests
PUT /api/manufacturing/stock/v1/requests/{requestId}
DELETE /api/manufacturing/stock/v1/requests/{requestId}
POST /api/manufacturing/stock/v1/requests/{requestId}/cancelRequest
- v1.1
GET /api/manufacturing/stock/v1.1/requests
GET /api/manufacturing/stock/v1.1/requests/{requestId}
POST /api/manufacturing/stock/v1.1/requests
PUT /api/manufacturing/stock/v1.1/requests/{requestId}
DELETE /api/manufacturing/stock/v1.1/requests/{requestId}
- v2
POST /api/manufacturing/stock/v2/request/{requestId}/cancelRequest?mandatoryParam=someValue |
Depois de um certo tempo, pode ser necessário reorganizar o cenário das APIs disponíveis, concentrando em uma única versão todas as alterações realizadas. Neste caso, aproveitando a evolução da versão da transação cancelRequest para 2.000 (que afetaria apenas um endpoint), podemos ter uma nova majorVersion abrangendo os demais endpoints da API:
| Bloco de código |
|---|
| title | Endpoints disponíveis |
|---|
|
- v1
GET /api/manufacturing/stock/v1/requests
GET /api/manufacturing/stock/v1/requests/{requestId}
POST /api/manufacturing/stock/v1/requests
PUT /api/manufacturing/stock/v1/requests/{requestId}
DELETE /api/manufacturing/stock/v1/requests/{requestId}
POST /api/manufacturing/stock/v1/requests/{requestId}/cancelRequest
- v1.1
GET /api/manufacturing/stock/v1.1/requests
GET /api/manufacturing/stock/v1.1/requests/{requestId}
POST /api/manufacturing/stock/v1.1/requests
PUT /api/manufacturing/stock/v1.1/requests/{requestId}
DELETE /api/manufacturing/stock/v1.1/requests/{requestId}
- v2
POST /api/manufacturing/stock/v2/request/{requestId}/cancelRequest?mandatoryParam=someValue
- v3
GET /api/manufacturing/stock/v3/requests
GET /api/manufacturing/stock/v3/requests/{requestId}
POST /api/manufacturing/stock/v3/requests
PUT /api/manufacturing/stock/v3/requests/{requestId}
DELETE /api/manufacturing/stock/v3/requests/{requestId}
POST /api/manufacturing/stock/v3/request/{requestId}/cancelRequest?mandatoryParam=someValue |
| Aviso |
|---|
|
Após a reorganização da API pode ser necessário excluir a versão anterior e neste caso, a depreciação deve ser feita conforme politica de cada linha de produto. |
