/v1, e /v1 é a única API pública: outras rotas usadas pelo console do muveya não são um contrato público, podem mudar a qualquer momento e não devem ser chamadas por integrações.
O compromisso
- Dentro de
/v1, as mudanças são aditivas. Uma operação, um campo ou um valor de que sua integração depende não é removido nem renomeado dentro de/v1. - Uma mudança incompatível exige uma nova versão. Ela é publicada como uma nova versão principal no caminho (
/v2), com um período de migração. A/v1não é quebrada no lugar. - O contrato é verificado a cada mudança. O contrato OpenAPI por trás das páginas de Endpoints é gerado a partir do código do muveya, e cada mudança é comparada com a versão anterior por uma verificação automática de compatibilidade que rejeita as mudanças incompatíveis listadas abaixo.
version que aparece dentro do documento OpenAPI é a revisão desse documento. A versão da API com que você se integra é o /v1 do caminho.
O que é considerado incompatível
O muveya considera incompatíveis estas mudanças na/v1 e não as faz dentro de /v1:
O que pode mudar dentro de /v1
Estas mudanças são aditivas e podem chegar a qualquer momento, anunciadas nas novidades:
- Novas operações e novos recursos.
- Novos parâmetros de consulta e cabeçalhos opcionais.
- Novos campos opcionais nas respostas.
- Novos valores em enumerações de resposta, por exemplo um novo status de pedido, um novo
typede movimento de estoque ou uma nova chave de métrica de análise. - Novos valores de
codede erro. - Novos escopos.
- Outra redação nos textos para pessoas:
titleedetaildos erros,labeldo resumo gerencial, descrições desta referência. - Valores operacionais que a API informa em tempo de execução, como o orçamento de limite de uso nos cabeçalhos de resposta.
catalog.cost:read) não é uma mudança de contrato: ele sempre foi documentado como opcional.
Escreva um cliente tolerante
1
Ignore campos que você não conhece
Interprete apenas os campos que você usa. Não falhe quando uma resposta trouxer um campo que não está no seu modelo.
2
Trate as enumerações como abertas
Dê a cada
switch sobre um status, um tipo de movimento ou uma chave de métrica um ramo padrão. Um valor novo não deve derrubar sua integração; registre-o e trate-o como “outro”.3
Trate campos opcionais como opcionais
Um campo marcado como opcional pode estar ausente. Ele nunca é enviado como
null no lugar (exceto três campos das análises, value, averageHours e maxAgeHours, descritos na referência). Verifique se ele existe antes de lê-lo.4
Decida pelo código e use o status como alternativa
Trate os códigos de erro que você conhece e use o status HTTP para qualquer código que ainda não conheça. Veja Erros.
5
Nunca decida por textos para pessoas
title, detail e label mudam com o idioma e com a redação. Use chaves, códigos e ids.6
Não dependa do formato do cursor nem da ordem das chaves
Os cursores são opacos e a ordem das chaves JSON não tem significado.
Descontinuação
Hoje nenhuma operação ou campo da/v1 está descontinuado, e nenhuma resposta traz cabeçalhos de descontinuação.
Quando existir uma /v2, a /v1 terá um período de desativação anunciado. A desativação será publicada nas novidades antes de entrar em vigor, e o muveya planeja sinalizá-la nas respostas com os cabeçalhos padrão Deprecation e Sunset.
O que não está na /v1 hoje
Recursos que não estão documentados nesta aba não estão disponíveis, por exemplo criar ou alterar pedidos pela API, ou webhooks. Se chegarem, chegarão como mudanças aditivas e serão anunciados nas novidades.
O único formato de chave de API emitido hoje é mvy_test_ (veja Autenticação).
Onde as mudanças são anunciadas
- As novidades listam as mudanças visíveis para clientes, da mais recente para a mais antiga.
- As páginas de Endpoints são regeradas a partir do contrato sempre que ele muda, em inglês, espanhol e português.