Anunciando o SDK Java da Vonage v7.0.0

Introdução

Desde que entrei na Vonage, tenho me dedicado a aprimorar o SDK principal do Java , reduzindo parte da dívida técnica e garantindo que ele esteja em dia com as especificações mais recentes especificações de API. Nesta postagem, explicarei algumas das principais mudanças no SDK e o que está por vir. Espero também conseguir convencê-lo a atualizar para a versão mais recente 🙂. Você também pode conferir as notas de lançamento de cada versão no GitHub.

Segurança

Se eu pudesse citar apenas um motivo para você atualizar, seria a segurança. As versões anteriores à 6.4.2 estão sujeitas a mais de 50 vulnerabilidades de segurança CVE devido a dependências desatualizadas (principalmente o Jackson, que é o que usamos para serialização JSON).

Antes da versão 7.0.0, o SDK dependia de uma pequena biblioteca interna para trabalhar com JWTs. Essa biblioteca não era atualizada há alguns anos e ainda estava sob a marca Nexmo. Agora, ela foi transferida para a organização da Vonage no GitHub (https://github.com/Vonage/vonage-jwt-jdk) e no Maven Central, passando por uma mudança de marca para garantir a consistência, além de atualizações de dependências por motivos de segurança.

Novos recursos

A novidade mais notável é a Messages API, que foi adicionada na versão 6.5.0 (leia sobre o anúncio aqui). Recentemente, escrevi um post no blog sobre a implementação do Messages v1 no SDK do Java, então espero que alguns de vocês que estão lendo isso já estejam usando-a! O suporte ao ponto de extremidade da API de Preços para consultar tarifas de saída para todos os países também foi adicionado na versão 6.5.0.

Dois novos recursos foram adicionados na versão 7.0.0. O recurso Premium de conversão de texto em fala já está em versão final (GA), portanto, o sinalizador para ativá-lo foi adicionado ao TalkAction NCCO. Agora você também pode solicitar pagamentos por telefone usando a nova ação “Pagar” do NCCO. Aqui está um link para a especificação.

Funcionalidades obsoletas e removidas

As remoções representam uma mudança incompatível, daí a atualização para uma versão principal. A API de Pesquisa por SMS já estava obsoleta há muito tempo e foi finalmente removida por completo; naturalmente, ela também foi removida do SDK. O campo legado de conversão de texto em fala voiceName text-to-speech também foi removido para desencorajar seu uso, já que estava obsoleto. Em vez disso, você deve usar o novo premium sinalizador, conforme descrito acima. Algumas refatorações internas também resultaram em algumas classes que nunca deveriam ter sido acessíveis publicamente (como as classes que terminam com Endpoint) se tornarem privadas ao pacote, conforme pretendido. AbstractClient não foi concebido como um recurso voltado para o público e não servia a nenhum propósito real internamente, por isso também foi removido. O mesmo vale para AbstractAuthMethod. Na remota hipótese de você estar dependendo do Apache Commons (especificamente, lang3, io e logging) fossem adicionadas como dependência implícita, elas também foram removidas.

A principal obsolescência a ser observada diz respeito à Redact API. Embora já faça parte do SDK há algum tempo, ela nunca saiu da fase de Developer Preview. Por política, o SDK Java oferece suporte apenas a APIs que estejam em “Disponibilidade Geral” (GA) nas versões principais; portanto, estamos descontinuando essa API com a intenção de removê-la até que tenhamos certeza de poder oferecê-la como um serviço GA. Além disso, o ipAddress campo em AdvancedInsightRequest foi marcado como obsoleto para refletir seu status de obsolescência na especificação da Number Insight API. Ele será removido na próxima versão principal.

Correções e melhorias

À medida que nossas APIs evoluem, os SDKs fortemente tipados precisam ser atualizados para refletir as mudanças nas especificações. Estamos atentos a casos em que o SDK não esteja em sincronia com a API, mas nem sempre conseguimos detectar tudo; portanto, por favor, relatem quaisquer problemas e tentaremos corrigi-los na próxima versão!

O CallEvent webhook não continha o call_uuid , que foi adicionado na versão 6.4.2. A com.vonage.client.sms.MessageStatus enumeração não incluía alguns dos códigos de erro descritos na especificação, o que já foi corrigido. Havia alguns problemas com as classes NCCO, que não estavam em conformidade com a especificação. Mais notavelmente, as Ações não estavam devidamente definidas no modelo de objeto, o que significava que a desserialização não estava funcionando conforme o esperado. SipEndpoint Faltava o headers e WebSocketEndpoint restingia incorretamente headers os valores do `Map` para `Strings`. Os endpoints do NCCO agora validam os uri campos usando java.net.URI. Os construtores também foram definidos como privados ao pacote; portanto, você deve obtê-los pelo builder() para garantir a consistência.

Implementação da Number Insight API no SDK do Java foi atualizada para ficar em conformidade com a especificação. Os problemas estavam relacionados, em sua maioria, a campos ausentes ou campos localizados na classe errada (algumas funcionalidades foram transferidas do insight Avançado para o Padrão, por exemplo). A documentação também foi aprimorada e complementada onde faltava. Algumas das enums internas (por exemplo, em AdvancedInsightResponse) foram transferidas para arquivos separados, de modo que, caso uma funcionalidade seja transferida, por exemplo, do “Advanced” para o “Standard”, não será necessária uma alteração compatibilidade no futuro. Valores adicionais para InsightStatus foram adicionados. Para a versão síncrona de AdvancedInsightRequest, um novo campo booleano realTimeData foi adicionado. Se definido como true, você receberá o status em AdvancedInsightResponse.

Foram feitas algumas correções na Messages API. Destacam-se, principalmente, as WhatsappTemplateRequestcampo parameters , que a especificação apresentava de forma enganosa como sendo um List<Map, String, ?>> quando, na verdade, deveria ser List<String>. Outra correção é no policy e locale campos. Como o primeiro possui um único valor válido no momento, ele é opcional na API. O segundo apresentava uma falha mais grave na versão 6.5.0, pois impedia o uso de configurações regionais com menos de 4 caracteres. Além disso, não ficava claro na documentação quais eram os valores válidos. Para evitar confusão, a lista completa de idiomas suportados pelo WhatsApp foi adicionada como uma enumeração; assim, em vez de passar uma String potencialmente inválida, você não precisa mais procurar o que é suportado — tudo está enumerado para você no SDK! De maneira mais geral, a validação do SDK para números de remetentes (ou seja, o from campo) estava incorreta para SMS, MMS e WhatsApp. Os remetentes de SMS e MMS agora podem conter caracteres alfanuméricos (ou seja, IDs), enquanto o remetente do WhatsApp deve ser um número de conta do WhatsApp Business.

De maneira mais geral, o SDK está um pouco mais organizado internamente (em termos de qualidade do código, consistência etc.) e apresenta maior cobertura de testes. Do ponto de vista do usuário, as outras melhorias diversas incluem a configuração de Content-Type, Accept e User-Agent cabeçalhos em solicitações de saída, bem como o uso explícito da codificação UTF-8. Para quem tem dúvidas sobre compatibilidade, nos empenhamos em oferecer suporte ao Java 8 por um bom tempo, a menos que haja um motivo mais convincente, do ponto de vista da manutenção, para migrar para a versão 11 ou 17. O SDK foi testado no JDK 18, portanto, qualquer versão moderna do Java é compatível no momento.

Roteiro

Além da manutenção de rotina para garantir que a implementação atual esteja em conformidade com as especificações da API e das correções gerais, a próxima grande novidade para o SDK do Java é a nova Video API, que atualmente está em fase beta. O SDK Java da OpenTok será descontinuado no futuro. Em vez de ter repositórios, artefatos, versões, bases de código etc. separados, decidimos otimizar a experiência do usuário integrando a funcionalidade de Video diretamente em nossos SDKs principais. Vamos implementar o suporte a ela nos SDKs de forma gradual por meio de versões beta; portanto, se você estiver interessado em experimentar os recursos de Video, fique de olho no Maven Central para as versões beta do SDK Java!

É claro que, enquanto isso, ainda haverá lançamentos da linha principal com patches, correções e até mesmo novos recursos GA, mas, nesse ínterim, estaremos trabalhando na implementação da Video API nos SDKs. Como a base de código do OpenTok é tão diferente, em termos de arquitetura, do SDK principal, isso vai significar uma reescrita completa para mim. Olhando mais adiante, estou ciente de que alguns usuários do SDK Java desejam solicitações e respostas assíncronas. Esse é o próximo item na minha lista de melhorias importantes para o SDK, então fiquem de olho aqui.

Encerrando

Por enquanto é só isso! Se você encontrar algum problema ou tiver sugestões de melhorias, fique à vontade para abrir um ticket no GitHubou entre em contato conosco no Twitter ou dar uma passada no nosso Slack da Comunidade. Espero que você tenha uma ótima experiência ao usar as APIs da Vonage com a versão mais recente do SDK para Java!