Controle de versão da API da FedEx

Na FedEx, usamos o controle de versão semântico para gerenciar as versões da API. Cada versão é representada pelo formato principal.secundária (por exemplo, API de Remessa 1.1). Uma nova versão principal significa que a mudança não é compatível com versões anteriores, e uma nova versão secundária indica uma mudança que é compatível com versões anteriores.

Na FedEx, seguimos o controle de versão simples de URIs. Isso significa que apenas o número da versão principal é representado no caminho do URI. Observe que os números de versões secundárias não são incluídos no caminho do URI. Essa estratégia usa o roteamento do URI para indicar versões específicas da API.

Exemplo: /ship/v1/shipments

Princípios básicos da estratégia do controle de versão

Nosso plano é lançar menos versões principais das APIs da FedEx e tornar obsoleta uma versão principal dois anos após o lançamento de uma nova versão principal. Por exemplo, depois que uma versão principal "N" for lançada, a versão "N-1" terá suporte por dois anos.

Exemplo: em 2020, a versão principal V1.0 é lançada. Se a versão principal V2.0 for lançada em 2021, a V1.0 se tornará obsoleta em 2023.

As versões secundárias oferecerão suporte à maioria das novas funcionalidades e às atualizações de recursos.

Exemplo: depois da versão principal 1.0, as versões secundárias 1.1, 1.2 etc. serão lançadas para introduzir novas funcionalidades e atualizações de recursos.

Em qualquer momento, todos os endpoints de uma API específica terão a mesma versão principal. A versão mais recente da documentação só estará disponível no FedEx Developer Portal. Contudo, a página de visão geral de cada API terá um registro de mudanças detalhando as mudanças da versão principal e das versões secundárias.

Quando são lançadas versões principais das APIs?

Estamos nos esforçando para limitar o número de versões principais de nossas APIs. Contudo, há casos em que é inevitável lançar uma nova versão principal. Estes são alguns dos motivos mais importante para o lançamento de uma nova versão principal:

• Quando um valor de enumeração existente é removido ou tem seu formato ou o próprio valor alterado na solicitação ou na resposta
  

  Exemplo: o valor de enumeração “GEOGRAPHIC_COORDINATES” do elemento locationSearchCriterion é removido na versão N; a sintaxe dos dados muda de YY-MM-DD para MM-DD-YYYY; mudança de tipo de localidade de FEDEX_ONSITE para ONSITE na resposta

• Quando um elemento existente é removido da solicitação ou da resposta
  

  Exemplo: o elemento pickupType é removido (ou renomeado) da solicitação de taxa na versão N

• Quando um método existente é removido
  

  Exemplo: não há mais suporte para o método de criação e cancelamento de etiquetas do FedEx Express na versão N

• Quando um elemento existente que era opcional ou condicional é mudado para obrigatório na solicitação
  

  Exemplo: o número de reserva agora é um elemento obrigatório em remessas do FedEx Express® Freight na versão N

• Quando há mudanças no projeto da API
  

  Exemplo: a estrutura da solicitação e da resposta é reorganizada

• Quando há mudanças nos códigos e nas mensagens de erro
  

  Exemplo: o código de erro mudou de INCORRECT.WEIGHT para WEIGHT.LIMIT.EXCEEDED

Quando são lançadas versões secundárias das APIs?

• Quando um novo valor de enumeração é adicionado
  

  Exemplo: uma nova oferta de transporte é adicionada ao elemento serviceType na versão N

• Quando um novo elemento é adicionado
  

  Exemplo: um novo elemento opcional para incluir o número de telefone do despachante em remessas internacionais

• Quando um novo método é adicionado
  

  Exemplo: um método para modificar documentos comerciais internacionais depois que eles são transferidos é adicionado na versão N.

• Quando um elemento existente que era obrigatório é mudado para opcional
  

  Exemplo: o ID do documento agora é opcional porque a FedEx pode obter o ID da documentação com base nas informações do usuário.