Controlo de versões das API FedEx
Na FedEx, utilizamos o controlo de versões semântico para gerir versões da API. Cada versão é representada pelo formato da versão principal.secundária (ou seja, API de Expedição 1.1). Uma nova versão principal significa que a alteração não é retrocompatível e uma nova versão secundária indica uma alteração retrocompatível.
Na FedEx, seguimos um controlo simples de versões de URI. Isto apenas envolve o número da versão principal representado no caminho de URI. Tenha em atenção que o número de uma versão secundária não é incluído no caminho de URI. Esta estratégia utiliza o encaminhamento de URI para identificar versões específicas da API.
Por exemplo: /expedição/v1/expedições
Princípios de orientação de estratégia de controlo de versões
Planeamos lançar menos versões principais para as API FedEx e descontinuar uma versão principal num período de 2 anos a partir do lançamento de uma versão principal mais recente. Por exemplo, a partir do momento em que a versão principal "N" é lançada, a versão "N-1" será suportada durante 2 anos.
Por exemplo: em 2020, é lançada a versão principal V1.0. Se, em 2021, for lançada a versão principal V2.0, a versão V1.0 será descontinuada em 2023.
As versões secundárias irão suportar a maioria das novas atualizações de funcionalidades.
Por exemplo: após a versão principal 1.0, as versões secundárias 1.1, 1.2, etc. serão lançadas para apresentar novas atualizações de funcionalidades.
A determinada altura, todos os pontos finais de uma API específica terão a mesma versão principal. A versão mais recente da documentação apenas estará disponível no FedEx Developer Portal. No entanto, haverá um registo de alterações na página Descrição geral de cada API que detalhará as alterações às versões principais e secundárias.
Quando são lançadas versões principais da API?
Esforçamo-nos para minimizar o número de versões principais das nossas API. No entanto, existem determinados casos nos quais uma nova versão principal é inevitável. Os seguintes são alguns dos principais motivos pelo lançamento de uma nova versão principal:
- Quando um valor de enumeração existente é removido ou o formato ou o próprio valor for alterado mediante pedido ou resposta
Por exemplo: o valor de enumeração "GEOGRAPHIC_COORDINATES" do elemento locationSearchCriterion é removido na versão N; a sintaxe de datas é alterada de AA-MM-DD para MM-DD-AAAA; alteração do tipo de localização de FEDEX_ONSITE para ONSITE em resposta
- Quando um elemento existente é removido mediante pedido ou resposta
Por exemplo: o elemento pickupType é removido (ou o seu nome é alterado) a partir de um pedido de tarifa na versão N
- Quando um método existente é removido
Por exemplo: o método para criar e cancelar etiquetas FedEx Express deixa de ser suportado na versão N
- Quando um elemento existente que costumava ser opcional ou condicional se torna obrigatório mediante pedido
Por exemplo: o número de reserva é agora um elemento obrigatório para as expedições FedEx Express® Freight na versão N
- Quando existem alterações ao design da API
Por exemplo: a estrutura de pedido e resposta é reorganizada
- Quando existem alterações aos códigos e mensagens de erro
Por exemplo: alteração do código de erro de INCORRECT.WEIGHT para WEIGHT.LIMIT.EXCEEDED
Quando são lançadas versões secundárias da API?
- Quando é adicionado um novo valor de enumeração
Por exemplo: novas ofertas de transporte são adicionadas ao elemento serviceType na versão N
- Quando é adicionado um novo elemento
Por exemplo: um novo elemento opcional para incluir o número de telefone do despachante em expedições internacionais
- Quando é adicionado um novo método
Por exemplo: um método para modificar documentos comerciais internacionais depois de os mesmos serem carregados é adicionado na versão N.
- Quando um elemento existente que costumava ser obrigatório se torna opcional
Por exemplo: a ID do Documento é agora opcional, uma vez que a FedEx pode derivar a ID da documentação com base nas informações do utilizador.
Perguntas Frequentes
Vai ter de atualizar o URI para a versão mais recente num período de 2 anos, para que a FedEx possa retirar a versão mais antiga.
As versões secundárias são lançadas para acolher novas funcionalidades e alterações que são retrocompatíveis. Deste modo, não esperamos que interrompam a integração. Não é obrigatório atualizar para uma nova versão secundária, mas a atualização para versões secundárias é recomendada, de modo geral, para consumir as novas funcionalidades criadas para dar resposta às necessidades dos clientes.
Nos Web Services FedEx, todas as alterações exigem um novo lançamento do WSDL ou uma versão principal, dificultando as atualizações para os clientes. Com as API FedEx, a maioria das novas funcionalidades pode ser introduzida através de versões secundárias, facilitando as atualizações aos clientes. Existirão mais versões secundárias e menos versões principais da API.
