No final de 2019, a indústria de API estava alvoroçada com alguns novos desenvolvimentos para duas linguagens de descrição principais: OpenAPI e JSON. O OpenAPI v2.0, quando era originalmente conhecido como Swagger 2.0, foi criado para ser um subconjunto estendido do esquema JSON. No último trimestre de 2019, o OpenAPI v3.0 atingiu até 90% de compatibilidade com o Draft 5 do JSON Schema, seu predecessor.
Essa foi uma ótima notícia para os desenvolvedores que passaram um tempo tentando unir palavras-chave que estavam, de certa forma, perdidas na tradução. Mas onde as duas divergiram em primeiro lugar, e quais estratégias os desenvolvedores usaram ao escolher entre elas? Além disso, o que a compatibilidade do OpenAPI e do esquema JSON tem a ver com o futuro do design de API?
Este artigo procura dar uma breve explicação sobre como os esquemas devem funcionar. Ele também irá detalhar a diferença entre os esquemas OpenAPI e JSON, e como esses dois funcionavam lado a lado. Este guia também deve provar o vantagens de um kit de ferramentas de especificação OpenAPI, uma vantagem para trabalhar com os formatos de descrição JSON e OpenAPI. E, por último, o artigo mudará todo o conhecimento anterior sobre JSON e OpenAPI, graças aos desenvolvimentos da indústria recentes, em fevereiro de 2020.
Uma revisão dos princípios básicos: esquemas, JSON e OpenAPI
Para aqueles que estão aprendendo sobre JSON e OpenAPI, uma das primeiras perguntas feitas é: o que é um esquema em primeiro lugar? No jargão do design de API, os esquemas são metadados que descrevem como os dados são estruturados. Um esquema, portanto, atua como um modelo para estruturar dados.
Tecnicamente falando, você poderia implementar os endpoints de uma API sem qualquer tipo de esquema em vigor. Mas uma geração anterior de desenvolvedores de API descobriu que a vida sem esquemas era incrivelmente difícil e confusa. Os desenvolvedores de hoje agora veem o valor de projetar APIs com um maior senso de estrutura. Para eles, os esquemas podem simplificar muito o trabalho de design de API complexo, combinando padrões de dados e organizando bancos de dados em blocos reutilizáveis. E os dois esquemas mais populares, usados como as proverbiais Rosetta Stones, são JSON e OpenAPI.
Mas é aqui que os dois diferem fundamentalmente. Enquanto o esquema JSON pode descrever instâncias de dados JSON (como aqueles encontrados em solicitações HTTP), OpenAPI pode descrever APIs inteiras. Ele faz isso em virtude dos vários formatos de Especificação de API que tem à sua disposição.
Dito isso, vamos analisar os problemas persistentes do OpenAPI e do esquema JSON.
Questões de compatibilidade
Conforme recontado acima, as versões do OpenAPI e JSON Schema por volta do final de 2019 eram 90% compatíveis entre si. Para alguns desenvolvedores, essa diferença de 10% contou muito. Ele ainda representava o fato de que a OpenAPI não conseguia reconhecer, muito menos oferecer suporte, algumas palavras-chave importantes do esquema JSON. Não era um problema para quem já usava o JSON Schema por padrão, mas era um ponto de frustração para aqueles que estavam acostumados com o OpenAPI.
As lacunas de compatibilidade significavam fazer uma de duas coisas. A primeira opção seria fazer o trabalho adicional de converter o esquema JSON em esquema OpenAPI. A segunda opção seria continuar usando o esquema JSON como de costume, mas também manter uma versão da API com palavras-chave que a OpenAPI suportaria.
Esses pontos de dor ainda existem, no entanto? Alguns desenvolvimentos recentes podem provar o contrário.
O futuro indica maior harmonia
Em fevereiro de 2020, o JSON Schema Draft 2019-09 e o OpenAPI v3.1 foram lançados. Entre outras coisas, o OpenAPI agora é definido como um pequeno superconjunto do esquema JSON e não mais um conjunto secundário ou um subconjunto. Especialistas em JSON e OpenAPI fizeram a feliz descoberta de que não há mais uma lista de palavras-chave com suporte. Isso porque todas as palavras-chave existentes no esquema JSON 2019-09 também podem ser usadas no OpenAPI v3.1. Em resumo, escolher entre OpenAPI e JSON Schema agora pode ser uma questão simples, sobre qual deles sua equipe tem mais conhecimento. Um ainda pode superar o outro como seu primeiro plano para projetar APIs. Agora que as ferramentas de design de API estão subindo de nível e ficando mais sincronizadas, é o momento perfeito para você investir nelas.
Do blog: Futureplay
