Preterir uma API da web: práticas recomendadas?

Eventualmente, você precisa depreciar partes da sua API da web pública. No entanto, estou confuso sobre qual seria a melhor maneira de fazê-lo. Se você possui uma grande base de aplicativos de terceiros, apenas arrancar versões antigas da API parece a maneira errada de fazer isso, pois quase todos os aplicativos falhariam da noite para o dia. No entanto, você não pode manter as APIs antigas da Web disponíveis para sempre, pois elas podem estar desatualizadas ou há mudanças significativas que tornam impossível trabalhar com ela.

Quais são algumas das práticas recomendadas para descontinuar APIs antigas da Web?

Parece que o pôster original já efetivamente, mas informalmente reprovou sua API (qualquer coisa que seja chamada de 'API antiga'). No entanto, até que seja anunciado e os usuários sejam notificados de que uma API está obsoleta, ela não está formalmente obsoleta.

A API preterida é um estágio intermediário e inativo do código. São os últimos ritos. Este é o período que permite aos adotantes / consumidores reconfigurar seus aplicativos para uma API mais nova e se despedir, fazendo as pazes com a API. Algumas APIs podem demorar mais que outras, mas neste momento sabemos que o tempo delas não é longo.

A API excluída é um funeral de código. Não há mais nada que ele possa fazer, mas descartado adequadamente e devidamente memorizado.

Muitos desenvolvedores de API e serviços optam por funerais em vez de realizar os últimos ritos; no entanto, acho que é um pouco arriscado. Se houve algum tipo de promessa de serviço ou suporte feita quando o API / serviço foi adotado inicialmente ou por meio de renovação, convém honrar esse compromisso por um período de tempo razoável antes de realizar o funeral.

Para bibliotecas que não são de serviço, acho que uma versão principal, independentemente do período de tempo, é provavelmente um período mais do que aceitável e justo de compatibilidade com versões anteriores garantidas. Além disso, depende da influência e do lobby dos usuários para estender sua vida além desse período. E não se surpreenda se, de tempos em tempos, houver objeções devido a insubstituíveis dependências de terceiros que estão presas no limbo e vinculadas a determinadas versões de determinadas plataformas.

Para serviços, suspeito que você queira analisar um período de seis meses ou ano, simplesmente por causa da variação de quem e como um serviço pode ser consumido e a variação do ciclo de desenvolvimento correspondente de um projeto para outro. muitos projetos que podem estar consumindo seu serviço ainda podem ter um grande projeto inicial e podem agendar um ciclo de lançamento por mais de um ano. A maioria das opiniões de desenvolvedores de fora sugeriria que aqueles com agendas longas são responsáveis ​​por cumprir seus tempos de ciclo, e esses projetos que consomem muito ciclo deveriam adotar um ciclo de liberação mais rápido, e isso pode ser verdade. Mas, em última análise, a data da exclusão é algo que você precisa negociar com os usuários.

Uma estratégia boa, mas não à prova de balas para descontinuação, pode ser ao cancelar a descontinuação, destacar o prazo para a intenção de excluir, juntamente com uma solicitação de comentário ou objeção em um formato de pesquisa das seções da API em questão. Se você não possui uma lista de contatos de usuários porque seu serviço opera com acesso [semi] anônimo, considere a possibilidade de procurar logs para usuários frequentes e ativos e enviar a notificação ao administrador do host ou domínio para encaminhar como bem entender.

A maioria das APIs da Web que eu uso (de empresas como Google, Yahoo! e Microsoft) tem um período de "pôr do sol". Os desenvolvedores são informados dentro de um prazo razoável (digamos, de 3 a 6 meses) dos recursos que serão depreciados para dar a eles tempo de sobra para atualizar com antecedência.

Você pode adicionar os detalhes dos períodos de expiração nos Termos de Serviço ou em outra documentação para que as pessoas estejam cientes de como isso funciona. Isso significa que quando alguém decide usar sua API, ele saberá com quais agendas precisa trabalhar. Por exemplo, você pode informar às pessoas que elas precisarão atualizar seu sistema uma vez por ano e com quatro meses de antecedência para fazê-lo.

Também é uma boa idéia usar a numeração de versões para que você possa dizer que, por exemplo, "a versão 3 será depreciada em breve, verifique se o código funciona com a versão 4" etc. Dessa forma, as pessoas sabem que, se o aplicativo estiver trabalhando com a versão 4 então eles estão prontos para o pôr do sol.

Informações adicionais do ângulo do processo:

• Comunique-se com todas as partes interessadas : forneça a outras equipes e consumidores de API uma comunicação clara e concisa sobre o motivo da depreciação da API, a estratégia, os detalhes do plano e do cronograma, o significado da versão e as alternativas, defina o HTTP de acordo.

• Planejar e agendar : No plano, você deve ter os principais marcos e a data prevista para o término da depreciação. Você deve pedir aos consumidores o mesmo e fornecer datas em que eles descontinuarão a chamada. Organize uma reunião regular para monitorar o processo e apoiar os consumidores.

• Controle de versão e fornecer alternativas : o controle de versão pode ajudar a mostrar alterações de última geração nas principais versões e tornar a estratégia de descontinuação da API.

• Defina o cabeçalho HTTP Response do pôr do sol : os cabeçalhos HTTP desempenham a parte técnica do aviso, os consumidores da API devem monitorar esse tipo de código para entender quando uma API está sendo descontinuada.

• Monitore o antes e o depois : monitore seus consumidores e alerte qualquer consumidor que ainda estiver usando a API após um determinado período são informações úteis para garantir que você não perca nenhum abandonware.

Além das respostas existentes, você deve fornecer uma substituição suspensa ou um plano de migração ao remover algo, para que seus usuários possam atualizar seu código.

Tente evitar remover a funcionalidade sem fornecer uma alternativa - isso deixaria alguns de seus usuários insatisfeitos.