Argumento obsoleto na API GraphQL (especificação 2021)

Não há uma ótima solução aqui, mas posso dizer o que minha equipe decidiu fazer: criar "um campo ao lado com o mesmo nome" (+ V2) ou criar um campo irmão com um "nome melhor", se você tiver um nome melhor.

Compensações entre versões e novos nomes:

• Se você escolher usar V2, não é tão "limpo", mas é fácil ver o que o consumidor da API deve fazer e o que deve usar. Às vezes, você pode até criar uma V2 antes de descontinuar a original, e alguém lendo o esquema pode ver a V2 e começar a trabalhar para isso. Além disso, esses clientes já estão olhando para picture, então é mais provável que vejam pictureV2antes que você diga a eles.
• Se você escolher um "nome melhor", o esquema final é "limpo"; ele não contém informações históricas de que costumava haver algo diferente. No entanto, se você introduzir um novo nome, você tem que ser explícito quando descontinuar, e você pode ter que se comunicar com mais cuidado. O consumidor da API precisa ler o aviso de descontinuação para saber o que fazer em seguida, já que não é imediatamente óbvio o que está acontecendo.

Também vale a pena notar que o problema da "limpeza" é uma coisa real, e não é apenas sobre estética. Provavelmente vai parecer ruim na primeira vez que você adicionar V*algo, mas descobri que em escala*, é mais fácil a longo prazo.

* "em escala" aqui pode significar algumas coisas diferentes, incluindo

• Crescimento do Schema: Quando você tem uma grande base de código ou esquema, que continua a crescer, essa questão vai surgir muito. Escolher uma estratégia de versionamento simples permite que a equipe não tenha que desacelerar para tomar uma nova decisão a cada vez. Basta aumentar a versão e seguir em frente.
• Crescimento da base de clientes: quando você tem uma grande base de consumidores de API, uma estratégia de controle de versão como essa é fácil de entender, então você não precisa reaprender várias vezes.
• Crescimento da equipe: quando você tem uma equipe grande, uma estratégia de versionamento que seja fácil para os novos membros da equipe verem de relance também não precisa ser reensinada. É fácil para a nova pessoa "copiar pasta" e saber o que fazer em seguida.
• Crescimento da arquitetura: se você acabar seguindo o caminho de subgráficos e federação, costura ou algo semelhante, ter uma estratégia simples e consistente em todos os sistemas levará à consistência e legibilidade para seu cliente, mesmo se você tiver equipes separadas trabalhando em sistemas separados.

Então, se um colega de equipe me mostrasse seu exemplo especificamente e perguntasse o que fazer em seguida, eu daria essas opções, e eles deveriam fazer o que é certo para seu produto e seu cliente.

1. pictureV2: Você conhece seu domínio e seu cliente. Se picturefor a palavra certa, use pictureV2.
2. pictureUrl: Você está retornando uma URL, que é um escalar. Você não está retornando uma "imagem", que pode ter dimensões, altText, títulos, etc. Além disso, se você usar o nome pictureUrlhoje (quando estiver retornando apenas uma URL), no futuro, se você QUISER introduzir essas outras propriedades, você pode usar picture(o nome não escalar) para isso . Eu não recomendo engenharia excessiva para o que "pode ​​acontecer", mas se você nomear as coisas com esse princípio em mente, você se deixa aberto para adicionar recursos no futuro sem ter que arquitetar demais para talvez, hoje.
3. image: Este termo transmite o mesmo significado relativo de "imagem", mas é mais comum em design de API.
4. imageUrl:A que eu geralmente recomendo, devido aos dois pontos anteriores.