Arquivo de Dicionário da TI

O JSON é um formato leve de intercâmbio de dados baseado em texto, projetado para facilitar tanto a leitura e escrita por humanos quanto o parsing e geração de código por máquinas. JSON significa JavaScript Object Notation (em tradução livre, Notação de Objeto JavaScript), pois, esse formato de dados utiliza uma sintaxe derivada de um subconjunto da linguagem JavaScript.

Porém, apesar de ser baseado em JavaScript, ele funciona de forma independente de qualquer linguagem de programação. Isso quer dizer que, na prática, você pode usar JSON para trocar dados entre sistemas escritos em diferentes linguagens, como Python, Java, C#, PHP, Ruby, e, claro, o próprio JavaScript, entre muitas outras opções.

A popularidade do JSON advém, em grande parte, de sua simplicidade e clareza. Ao contrário de formatos mais verbosos como XML, ele evita a necessidade de tags de fechamento complexas e estruturas hierárquicas que podem tornar a leitura e o processamento mais lentos e suscetíveis a erros.

1 – Estrutura e tipos de dados fundamentais

Os documentos JSON possuem uma estrutura composta por dois tipos principais: os objetos e os arrays.

Objetos ({ }): um objeto é uma coleção de dados não ordenada de pares de nome/valor. Cada par consiste em um nome (uma string) seguido por dois pontos (:) e um valor. Os pares são separados por vírgulas. Pense em um objeto como um dicionário ou mapa, onde cada nome é uma chave única que aponta para um valor. Exemplo:

{
  "nome": "João Silva",
  "idade": 30,
  "cidade": "São Paulo"
}

Arrays ([ ]): um array, por sua vez, é uma coleção ordenada de valores. Os valores são separados por vírgulas. Arrays são ideais para representar listas de itens. Exemplo:

[
  "maçã",
  "banana",
  "laranja"
]

Dentro de objetos e arrays, os valores podem ser de diversos tipos:

String: uma sequência de caracteres, envolta em aspas duplas. Ex: "texto"
Number: um número inteiro ou de ponto flutuante. Ex: 10, 3.14
Boolean: true ou false.
null: representa a ausência de valor.
Object: um objeto JSON aninhado.
Array: um array JSON aninhado.

A combinação de objetos e arrays, junto com os tipos de dados básicos, permite que os desenvolvedores criem estruturas de dados complexas e flexíveis, capazes de representar praticamente qualquer tipo de informação.

2 – Aplicações comuns

O JSON não é apenas mais um formato de dados; ele se tornou um padrão para a comunicação e o armazenamento de informações. Algumas das suas aplicações mais comuns são:

APIs REST: o JSON é o formato de intercâmbios de dados mais utilizado em APIs modernas, especialmente as APIs que possuem arquitetura REST.
Configurações de Aplicações: muitos softwares utilizam arquivos JSON para armazenar configurações. São exemplos dessas ferramentas o ESLint, Prettier, Babel, entre outros.
Bancos de Dados NoSQL: bancos de dados como MongoDB, Couchbase e Firebase utilizam JSON ou formatos baseados nele para armazenar seus documentos.
Webhooks: ferramentas que enviam dados de um aplicativo para outro frequentemente usam JSON para enviar seus payloads. Serviços como Stripe, GitHub e Zapier são bons exemplos disso.
Integração de Sistemas: desenvolvedores utilizam o JSON para facilitar a troca de informações entre microsserviços e sistemas distribuídos, além de manipulá-lo diretamente no front-end com frameworks JavaScript como React e Angular por exemplo, para fazer requisições e receber dados do back-end.

3 – Vantagens do JSON

Leveza: os arquivos JSON tendem a ser menores do que os seus equivalentes em XML.
Facilidade de leitura e escrita: tanto por humanos quanto por máquinas.
Suporte nativo: quase todas as linguagens modernas possuem bibliotecas integradas para trabalhar com esse formato.
Interoperabilidade: como é baseado em texto e padronizado, pode ser usado em qualquer ambiente.

4 – Limitações e Cuidados

Não suporta comentários: diferente de arquivos .js ou .yaml, por exemplo, que possuem operadores específicos para comentários.
- Sem suporte a tipos de dados complexos: tipos de dados como Date, Function, ou undefined não são suportados diretamente, o que pode exigir tratamentos mais específicos desses dados nos sistemas que os manipulam.
Case-sensitive: "Nome" e "nome" são chaves diferentes, o que exige atenção por parte dos desenvolvedores.
Validação pode ser rígida: estruturas mal formadas causam erro no parsing. Por isso, os desenvolvedores costumam aplicar validações via JSON Schema, principalmente em APIs, para garantir que os dados estejam no formato correto antes de processá-los.

5 – Ferramentas Úteis para Trabalhar com JSON

JSON Formatter & Validator (https://jsonformatter.org/): site útil para formatar, validar e visualizar JSON de forma agradável.
Postman & Insomnia: ambas são ferramentas populares para testar e documentar APIs que trabalham com JSON.
jq: utilitário de linha de comando leve e simples para processar e manipular arquivos JSON.
VS Code + Extensões: o editor já vem com suporte embutido para JSON, incluindo validação e autocompletar.

Gostou do conteúdo? Compartilhe com seus amigos e aproveite para conhecer mais termos da área de TI aqui!

API, é a sigla para Application Programming Interface, que em português significa Interface de Programação de Aplicações. APIs podem ser entendidas como pontes digitais, pois, elas são recursos que servem para conectar (ou integrar) diferentes sistemas e aplicações, independentemente, das tecnologias utilizadas em seu desenvolvimento.

As APIs permitem que diferentes sistemas e aplicações “conversem” entre si de forma padronizada, ao estabelecer padrões de comunicação chamados de contratos. Nesses contratos, estão definidos quais dados podem ser transacionados, sua obrigatoriedade ou não, e suas respectivas estruturas, tanto de requisições quanto de respostas da API.

As APIs são parte da rotina de trabalho de desenvolvedores e um importante recurso de integração de sistemas. Imagine a seguinte situação: um desenvolvedor recebe a tarefa de criar um sistema de e-commerce. Entre suas responsabilidades, uma delas é implementar o sistema de processamento de pagamentos, a qual é uma funcionalidade crítica para o sistema.

Nesse cenário, sem o auxílio das APIs, certamente, desenvolver essa funcionalidade do zero demandaria muito tempo e um enorme esforço, pois seria necessário:

Criar todo o sistema de segurança
Integrar com bancos e operadoras
Lidar com regulamentações financeiras
Garantir conformidade com PCI DSS

Com as APIs? O desenvolvedor pode simplesmente se conectar ao sistema de pagamentos de uma empresa como a Stripe, PayPal ou PagSeguro e pronto! Com apenas algumas linhas de código, é possível implementar um sistema de pagamentos robusto e seguro, sendo necessário apenas encaminhar os dados solicitados por esse serviço e processar a resposta recebida. Tudo isso sem precisar construir a funcionalidade do zero.

E essa é uma das grandes vatangens das APIs: permitir a integração de diferentes serviços, reaproveitando soluções já prontas e otimizadas. Os ganhos estão na aceleração do processo de desenvolvimento, na redução de custos e na maior qualidade das entregas.

1 – APIs e a arquitetura cliente-servidor

As APIs funcionam baseadas na arquitetura cliente-servidor, onde:

O cliente realiza solicitações (geralmente requisições HTTP) para um servidor;
O servidor recebe as solicitações e é responsável por processar cada uma delas e retornar uma resposta para o cliente.

Para compreender melhor essa relação entre a arquitetura cliente-servidor e as APIs imagine que um usuário acessa o aplicativo ou site de um e-commerce e faz uma compra. Para que esse pedido seja gerado com sucesso, o pagamento precisa ser processado e aprovado. Na arquitetura cliente-servidor, um processo semelhante a esse acontecerá:

Cliente faz a requisição: o sistema de e-commerce realiza uma requisição de pagamento para a API do fornecedor.
Servidor recebe e processa: o servidor do fornecedor do sistema de pagamento, irá validar os dados recebidos, consultar bases de dados, executar regras de negócio, entre outros.
Servidor responde: por fim, o servidor irá retornar uma resposta de sucesso ou falha para essa requisição.

No final desse processo o usuário receberá um retorno, positivo ou negativo, conforme o resultado da requisição realizada entre cliente (no caso, o sistema de e-commerce) e servidor (o fornecedor do sistema de pagamentos).

2 – Tipos de APIs

Podemos classificar as APIs pelo seu tipo de acesso e tipo de arqtuitetura, da seguinte forma:

2.1 – Por tipo de acesso

API Pública: são APIs abertas ao público em geral, podendo ser acessadas e usadas por qualquer pessoa ou organização. São exemplos as APIs do Twitter, GitHub ou Google Maps. Elas democratizam o acesso a dados e funcionalidades.

API Privada: são APIs restritas ao uso interno de uma organização ou instituição. Podemos imaginar como exemplo, uma API que conecta o sistema de vendas com o sistema de logística da empresa.

API de Parceiros: são APIs usadas entre organizações parceiras, conforme contratos comerciais e interesses mútuos.

2.2 – Por tipo de arquitetura

API SOAP (Simple Object Access Protocol – Protocolo de Acesso a Objetos Simples): é um protocolo de construção de APIs mais tradicional, onde cliente e servidor trocam mensagens usando XML. É um protocolo altamente estruturado sendo, geralmente, utilizado em APIs legadas e privadas. As APIs SOAP transmitem mensagens maiores em comparação com as outras arquiteturas, o que torna a comunicação mais lenta e dificulta a escalabilidade.

API RPC (Remote Procedure Call – Chamada de Procedimento Remoto): são APIs baseadas na chamada de funções em servidores remotos. Algumas informações são transmitidas para o servidor e a função é executada, remotamente, retornando ao cliente o resultado, como se a função tivesse sido executada localmente. O RPC se mostra muito útil quando é necessário executar uma função complexa sem comprometer os recursos locais, usando os recursos de um servidor remoto.

API REST (Representational State Transfer – Transferência Representacional de Estado): é a arquitetura de design de APIs mais utilizada na atualidade. Caracterizada pela simplicidade e flexibilidade, utiliza o protocolo HTTP para comunicação e transfere os dados, geralmente, em formato JSON. As requisições das APIs REST são baseadas nos verbos HTTP, os quais formam o chamado CRUD (Create (GET), Read (POST), Update (PUT), Delete (DELETE)).

GraphQL: trata-se de uma linguagem de consulta desenvolvida especificamente para APIs. As APIs desenvolvidas em GraphQL tem como principal diferencial fornecer exatamente os dados solicitados pelo cliente e nada além disso. Essa característica evita o tráfego desnecessário de dados e aumenta a eficiência e performance dos sistemas. APIs baseadas em GraphQL podem ser alternativas para as APIs REST, ou podem ser usadas em conjunto com esta arquitetura, dependendo das necessidades de cada projeto.

3 – Documentação de APIs

A documentação de uma API é crucial para o seu sucesso e nunca deve ser negligenciada. Ela fornece aos desenvolvedores as informações necessárias para interagir corretamente com a API, compreendendo suas funcionalidades, requisitos de autenticação, limitações e padrões de erro.

Para ser eficaz, a documentação deve ser:

Clara e Concisa: procure utilizar textos diretos e detalhados o suficiente para que qualquer desenvolvedor possa entender.
Atualizada: sempre que houverem atualizações na API, atualize a documentação.
Estruturada: siga uma lógica clara, incluindo endpoints, métodos, exemplos de requisições e respostas, e parâmetros.
Interativa: utilize diagramas, exemplos de código e sandboxes para facilitar a compreensão.
Acessível: facilite o acesso à documentação, mantendo-a disponível online e incorporando recursos de pesquisa e navegação.

Para facilitar seu trabalho não deixe de utilizar ferramentas específicas para documentação de APIs, como o Swagger e o Postman. Essas ferreamentas são essenciais no processo de documentação e permitem realizar entregas de maior qualidade:

Swagger: baseado no OpenAPI, permite criar, descrever e visualizar APIs RESTful. Seu editor interativo e o Swagger UI facilitam o teste de endpoints diretamente no navegador.
Postman: mais do que uma ferramenta de teste, oferece funcionalidades robustas de documentação. Permite criar documentações interativas, compartilhar coleções de requisições e integrar testes automatizados para manter a documentação alinhada ao comportamento da API.

Por fim, lembre-se que além das ferramentas, a equipe deve adotar uma abordagem contínua e colaborativa na criação e manutenção dos documentos. Uma cultura de documentação contínua permite manter o conteúdo relevante e útil ao longo do tempo..