A DOCE HARMONIA ENTRE JSON E API'S: DESVENDANDO A IMPORTÂNCIA DESSA ALIANÇA PODEROSA

#API Rest

Nas últimas décadas, a sociedade se tornou cada vez mais dependente da computação. E, com o grande volume de dados que é gerado diariamente, fica evidente que a computação ainda desempenhará e terá uma importância salutar para as sociedades humanas vindouras.

E, com essa quantidade astronômica de dados, as pessoas desenvolvem diversas APIs (Application Programming Interface) para uma infinidade de razões, tais como facilitar processos internos, um produto externo para clientes, ou construir uma ferramenta para terceiros.

É justamente nessa esteira que entra o JSON (JavaScript Object Notation), pois desempenha um papel basilar na interação entre as API’s e seus sistemas. Por ter sua sintaxe simples e facilmente legível, o JSON acabou se transformando em um formato universal para a troca de dados estruturados.

É nesse sentido que se pode falar da doce harmonia entre JSON e API’s. E tal harmonia abre um vasto caminho para construir ecossistemas digitais robustos e interconectados. Utilizando adequadamente p JSON, os desenvolvedores podem criar API’s mais eficientes, escaláveis e flexíveis.

Dessa forma, pode-se criar API’s inovadoras cuja troca de informações ocorre de forma fluída e eficaz. Por isso, o JSON tem seu papel central na era digital, pois promove comunicação ágil e eficiente entre sistemas, o que possibilita a colaboração entre desenvolvedores de todo o mundo.

Neste artigo, pretendemos abordar a importância do JSON para as API’s. De forma muito concisa, discutiremos o formato JSON e suas peculiaridades na era digital. Em seguida, trataremos do JSON enquanto uma linguagem de comunicação entre Cliente e servidores.

Depois, apresentamos e discutiremos o uso de JSON nas API’s em casos reais que demonstram o lugar central do JSON no desenvolvimento de novas aplicações.

INTRODUÇÃO

Conforme já mencionamos, o JSON tem um espaço central dentro do escopo do desenvolvimento de novas aplicações, pois contém traços idiossincráticos que torna seu manuseio muito simples.

Por permitir a transferência eficiente de informações entre clientes e servidores, o JSON facilita a comunicação em ambientes distribuídos. Além disso, a sua ampla adoção nas API’s decorre de sua compatibilidade com diversas linguagens de programação.

Outra característica peculiar do JSON é a sua capacidade de representar hierarquicamente informações complexas, oferecendo, também, flexibilidade para evolução e escalabilidade, isto é, permite adicionar ou remover campos sem que a compatibilidade com versões anteriores das API’s seja quebrada.

(Fonte).

Utilizar JSON nas API’s traz diversos benefícios aos desenvolvedores, tais como a eficiência na transmissão de dados, pois seu tamanho é compacto e é de fácil manipulação e leitura. Adicionalmente, ele pode ser integrado a diversas bibliotecas e frameworks.

Dessa forma, com todas essas vantagens do uso combinado do JSON com as API’s, diversas empresas dos mais variados setores têm utilizado essa combinação para simplificar a integração de suas aplicações, visando a eficiência de suas API’s.

DESVENDANDO O JSON: UMA LINGUAGEM UNIVERSAL

O que é JSON?

O acrônimo JSON significa JavaScript Object Notation e deriva dos literais da linguagem de programação JavaScript[1]. Nesse sentido, podemos dizer que o JSON é um subconjunto da linguagem JavaScript. Sendo um subconjunto, ele não é uma linguagem de programação, mas um formato de troca de dados[1].

Dessa forma, ele é conhecido como o padrão de intercâmbio de dados[1]. Em outras palavras, isso significa dizer que o JSON pode ser usado nos contextos onde ocorrem trocas de dados, quer entre navegador e servidores ou servidores e servidores, entre outros, por exemplo.

(Fonte).

Historicamente, é atribuída a Douglas Crockford a criação do JSON[1]. Embora o próprio Crockford reconhece que apenas deu nome e formalizou sua gramática dentro do Request For Comments(RFC) 4627[2], que se tornou o documento padrão que define o formato JSON e seus tipos de mídia[1][2].

Este documento escrito em 2006 introduz ao mundo o tipo de mídia registrado como application/json, cuja extensão é .json e também define a composição do JSON[1][2]. E o JSON acabou sendo reconhecido oficialmente como um padrão ECMA em 2009[1].

(Douglas Crockford. Fonte).

Todavia, em 2014, o Internet Engineering Task Force (IETF), por meio da RFC 7159[3] também publicou seu próprio padrão JSON, cujo esforço principal é limpar as especificações originais[2][3].

O padrão ECMA nos sugere que um texto JSON válido pode aparecer no formato de qualquer valor JSON reconhecido[1][2]. Já o padrão IETF diz-nos que um texto JSON válido deve abranger qualquer valor JSON dentro de um objeto inicial ou arranjo[1][3]. Essa é a principal diferença entre os dois padrões.

Conforme também já mencionamos, por ser um subconjunto do JavaScript, o JSON continua sob o mesmo conjunto de regras definido pela ECMA-262-Standardization[1]. Além disso, o JSON não é um formato verborrágico, daí vem a sua importância como um formato de dados, principalmente no ambiente Web[1][2].

A gramática do JSON

De forma bastante simplificada, podemos afirmar que o JSON é uma representação textual, a qual é definida por um pequeno conjunto de regras, na qual os dados estão estruturados[2].

Diante disso, fica evidente que o JSON se constitui como um formato de dados leve, legível e de fácil entendimento. Em termos de sintaxe, é bastante semelhante com a notação de objetos JavaScript. Logo, ele acaba sendo familiar para os desenvolvedores que já trabalham com essa linguagem.

(Fonte).

Há basicamente duas formas de fazer uma representação dos dados, isto é, os dados podem estruturados como:

Uma coleção de pares chave/valor;
Uma lista ordenada de valores;

Assim, cada par chave/valor forma uma chave (uma string) e um valor associado a esta chave. Dessa forma, dentro de um arquivo JSON as chaves são únicas, servindo, portanto, de identificadores para o acesso aos valores correspondentes[1][2]. E tais valores podem ser dos mais diferentes tipos, tais como:

Strings;
Números;
Booleanos;
Objetos aninhados;
Arranjos;

Sua sintaxe é extremamente simples. Cada objeto JSON é delimitado por chaves “{“ e “}”[1][2]. Confinados pelas chaves, temos os pares de chave/valor, separados por vírgulas. Cada par é separado entre si por dois pontos “:”[2]. As strings devem estar entre as aspas duplas, conforme o modelo abaixo:

{
"nome": "João",
"idade": 25,
"email": "joao@example.com",
"ativo": true
}

O trecho de código acima é um objeto JSON básico que representa um usuário. Adicionalmente, poderíamos ainda aninhar objetos e criar arranjos, permitindo a representação de estruturas de dados mais complexas, como podemos constatar no trecho de código abaixo:

{
"nome": "João",
"idade": 25,
"enderecos": [
  {
    "rua": "Rua A",
    "cidade": "São Paulo"
  },
  {
    "rua": "Rua B",
    "cidade": "Rio de Janeiro"
  }
]
}

Com essa visão geral das características e sintaxe do JSON, podemos verificar que sua estrutura é simples e flexível, o que o torna amplamente adotado como um formato padrão para troca de dados estruturados, especialmente no contexto das API’s.

Adicionalmente, diante de tanta simplicidade, flexibilidade e leveza do formato JSON, os sistemas que interagem com as API’s conseguem compreender mais facilmente e processar os dados estruturados no formato JSON, decorre daí seu posto de formato padrão de troca de dados estruturados.

Por que o JSON é amplamente adotado nas API’s?

Podemos responder à pergunta anterior a partir de três pilares:

Simplicidade e legibilidade;
Suporte multiplataforma;
Compatibilidade com diversas linguagens de programação;

Quanto à simplicidade e à legibilidade, o JSON se destaca uma vez que sua sintaxe é muito fácil de entender, pois é estruturado nos pares chave/valor e nas listas ordenadas de valores[1][2]. Portanto, um arquivo JSON é facilmente lido por humanos e máquinas, já que a leitura é intuitiva.

Como os dados são representados em formato de texto plano, a sua estrutura hierárquica clara tem como objetivo facilitar a compreensão de desenvolvedores cujo trabalho principal é com API’s.

(Fonte).

Ademais, por ser simples, este formato contribui para a facilidade de uso, manutenção e depuração das API’s, contribuindo para que o desenvolvimento de sistemas seja menos complexo, trazendo ganhos substanciais para as empresas e os desenvolvedores.

No trecho abaixo, exemplificamos um objeto JSON, cuja leitura pode ser facilmente feita, tomando como caminho o par chave/valor (Temos um indivíduo chamado Maria, cuja idade é 30 anos e mora na cidade de São Paulo):

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

Como dizemos, a leitura se torna fluida em razão do par chave/valor, que tanto um humano quanto um sistema podem ler sem maiores dificuldades, já que a sintaxe é clara e intuitiva[1][2].

Quanto ao suporte multiplataforma, o JSON, sem dúvidas, é o formato que possui grandes vantagens nessa parte. Sendo assim, um arquivo JSON pode ser interpretado e processado em diferentes sistemas e plataformas.

(Fonte).

Outra vantagem interessante é que esse processamento independe do ambiente onde os sistemas estão sendo executados. Em outras palavras, como o JSON é baseado na notação de objetos JavaScript[1][2], há suporte para ele em diversas tecnologias e linguagens de programação.

Em razão disso, o JSON se constitui como um formato facilmente utilizado em diferentes cenários, o que inclui:

Aplicações Web;
Sistemas Mobile;
Backend;

E isso garante que haja a interoperabilidade entre os diferentes sistemas e tecnologias. Por exemplo, em JavaScript podemos ter:

const jsonData = '{"nome": "Maria", "idade": 30, "cidade": "São Paulo"}';
const obj = JSON.parse(jsonData);
console.log(obj.nome); // Saída: Maria

Utilizando JavaScript, podemos converter uma string JSON para um objeto JavaScript através da função “JSON.parse()”. Como o JavaScript é uma linguagem suportada em diversas plataformas, por ampliação, podemos também dizer que o formato JSON também tem suporte multiplataforma.

Quanto à compatibilidade com diversas linguagens de programação, podemos afirmar que o JSON é um formato que pode ser trabalhado com diversas linguagens, utilizando bibliotecas nativas ou não[1].

As bibliotecas instrumentalizam uma dada linguagem de programação com as ferramentas necessárias para a manipulação e o processo de arquivos JSON, tais como a serialização (conversão de objetos para JSON) e a desserialização (conversão de JSON para objetos) de forma muito simples e eficiente.

(Fonte).

Por esse motivo também os desenvolvedores e as empresas escolhem o formato JSON como o ideal para a troca de dados estruturados, pois ele garante a interoperabilidade entre diferentes tecnologias e linguagens, o que viabiliza a comunicação entre diferentes sistemas sem maiores problemas.

No código abaixo, utilizando a linguagem de programação Python e o módulo “json”, podemos carregar o JSON em uma estrutura de dados nativa.

import json

jsonData = '{"nome": "Maria", "idade": 30, "cidade": "São Paulo"}'
obj = json.loads(jsonData)
print(obj["idade"]) # Saída: 30

Isso indicia que o JSON tem grande destaque entre os formatos para troca de dados estruturados, já que permite serialização e desserialização dos dados em diferentes ambientes. Para exemplificar a versatilidade do JSON, mostraremos mais dois exemplos em C e Java:

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <cjson/cJSON.h>

int main() {
  const char *jsonData = "{\"nome\": \"Maria\", \"idade\": 30, \"cidade\": \"São Paulo\"}";
  cJSON *json = cJSON_Parse(jsonData);
  if (json != NULL) {
      cJSON *nome = cJSON_GetObjectItemCaseSensitive(json, "nome");
      if (cJSON_IsString(nome) && (nome->valuestring != NULL)) {
          printf("Nome: %s\n", nome->valuestring);
      }
      cJSON_Delete(json);
  }
  return 0;
}

No trecho de código acima, utilizando a linguagem C e a biblioteca cJSON, somos capazes de processar o JSON. A função “cJson_Parse()” analisa a string JSON e tem como retorno um objeto cJSON, o qual pode ser manipulado pela linguagem C, como imprimir determinados valores.

No código abaixo, usando Java e a classe “JSONObject”, podemos processar e manipular um arquivo JSON. A classe mencionada acima permite que o programa acesse os valores do JSON utilizando os métodos específicos para isso, como o “getString()”, que, no nosso caso, obtém o valor da chave “nome”.

import org.json.JSONObject;
 
public class JSONExample {
  public static void main(String[] args) {
      String jsonData = "{\"nome\": \"Maria\", \"idade\": 30, \"cidade\": \"São Paulo\"}";
      JSONObject jsonObject = new JSONObject(jsonData);
      String nome = jsonObject.getString("nome");
      System.out.println("Nome: " + nome);
  }
}

Com os exemplos acima, fica cada vez mais evidente que o JSON pode ser utilizado em diversas linguagens de programação. Como as diferentes linguagens “entendem” ou “sabem como ler” um arquivo JSON, é possível dizermos que há suporte para manipulação e processamento de JSON em várias linguagens.

Em face disso, diversos sistemas e API’s podem trocar dados estruturados sem maiores problemas, mesmo que tais sistemas e API’s tenham sido desenvolvidos em linguagens de programação diferentes e para ambientes diversos.

Por isso, o JSON é uma escolha versátil e largamente empregado para a troca de dados nas API’s, sem qualquer especificação da linguagem de programação utilizada.

JSON COMO A LINGUAGEM DA COMUNICAÇÃO ENTRE CLIENTES E SERVIDORES

A importância da comunicação entre clientes e servidores

Na era da informação, a comunicação entre clientes e servidores é certamente uma parte essencial no que concerne a arquitetura de sistemas distribuídos.

Considerando uma arquitetura cliente-servidor típica, considera-se como clientes os dispositivos ou aplicativos que solicitam recursos ou serviços. Os servidores são, por outro lado, os grandes responsáveis por fornecer tais serviços ou recursos[1][4].

Para que isso ocorra, é necessário que os clientes e os servidores se comuniquem, trocando informações, tais como solicitações, respostas e dados, a fim de que haja a interação e compartilhamento de recursos[4].

Todavia, essa comunicação entre clientes e servidores precisa ocorrer de forma eficiente e confiável, de modo que as aplicações possam funcionar corretamente. É por meio da comunicação que os clientes enviam solicitações aos servidores e recebem as respostas esperadas.

(Fonte).

Através da comunicação, os dados são atualizados, as tarefas executadas e as informações necessárias são atualizadas para os usuários. Exemplo: se o usuário entrar em site para ver a previsão do tempo, a aplicação do site precisa se comunicar com um servidor que oferece as informações atualizadas[4].

Então, a aplicação do site ou móvel recebe um arquivo JSON do servidor com as informações da previsão do tempo relevantes e atualizadas e as exibe a previsão do tempo segundo o layout, o design daquele site específico.

Nesse sentido, a comunicação precisa ser adequada, como forma de garantir a segurança, autenticação e controle de acesso aos recursos. É nesse contexto que o JSON desempenha um papel fundamental como a linguagem da comunicação entre clientes e servidores.

Utilizamos o JSON par estruturar e transmitir os dados entre os clientes e servidores em uma dada interação. A sua utilização, enquanto formato de troca de dados, viabiliza uma comunicação eficiente, transmitindo as informações estruturadas de forma clara e concisa.

Benefícios do uso de JSON nas API’s

O uso de JSON no contexto das API’s apresenta diversos benefícios. Podemos elencar os seguintes:

Estrutura de dados simplificada: o JSON viabiliza uma forma simples e intuitiva de representar os dados;
Linguagem independente: o JSON é um formato de dados independente de linguagem, o que implica dizer que qualquer linguagem de programação é capaz de manipulá-lo e processá-lo;
Suporte amplo: o JSON tem suporte na maioria das linguagens de programação modernas, às vezes não depende nem de importar bibliotecas de terceiros;
Leveza e eficiência: o JSON é um formato de dados leve, que consome menos largura de banda e recursos da rede, gerando requisições e respostas mais rápidas, melhorando o desempenho das API’s;

Eficiência na transmissão de dados

Naturalmente, uma das características principais do JSON é a sua eficiência na transmissão dos dados, decorrente dos seguintes fatores:

Tamanho compacto: o JSON tem uma estrutura de dados simples e concisa, resultando, assim, numa representação compacta dos dados. Em outras palavras, são necessários menos bytes para a transmissão de dados;
Serialização e Desserialização: o JSON permite que os objetos sejam serializados e desserializados de forma rápida e eficiente, prevenindo erros;
Suporte a compressão: o JSON possui estrutura simples, o que favorece sua compressão por meio de algoritmos especiais. Tal compactação reduz ainda mais o tamanho dos dados no momento da transmissão, economizando banda e recursos;

Facilidade de leitura e manipulação

Neste artigo acima, já exemplificamos como o formato JSON pode ser utilizado por diferentes linguagens de programação. Isso demonstra a existência de uma integração e uma interoperabilidade com diversas bibliotecas e frameworks.

Dependendo das bibliotecas, esses recursos podem ser mais ou menos avançados, dependendo, logicamente, da necessidade das aplicações e dos usuários. Conforme vimos, essas bibliotecas oferecem os métodos e as funções para que o trabalho com o JSON seja menos complexo.

Os métodos e as funções permitem que operações simples, tais como a serialização e a desserialização, validação de esquema, busca e extração de dados, etc., sejam feitas de forma simplificada, com ganho de tempo real para os desenvolvedores e também exigindo menor poder de processamento.

E muitos frameworks populares, tais como o Express.js em JavaScript, Flask em Python e o Spring em Java, são compatíveis com o formato JSON, o que acaba por permitir a integração suave entre diferentes ecossistemas de desenvolvimento.

Flexibilidade para evolução e escalabilidade

Ainda no contexto atual, com a profusão de dados sendo gerados, o formato JSON permite flexibilidade para evolução e escalabilidade. Pois, a adição de novos campos pode ser feita de forma simplificada, inserindo ou removendo campos sem que a compatibilização com as versões anteriores seja perdida.

Havendo a necessidade de introduzir alterações nas estruturas dos dados nas API’s, podemos criar diferentes versões do JSON afim de que a compatibilidade retroativa seja garantida. A utilização das versões JSON anteriores pode ser continuada até que haja a migração definitiva para as novas.

Por fim, o JSON é extremamente adequado para ambiente escaláveis, nos quais vários sistemas se interagem entre si. Por sua estrutura simples, ele potencializa a distribuição e o processamento de dados nos sistemas distribuídos, o que facilita a escalabilidade horizontal.

EXEMPLOS DE USO DE JSON NAS API’S

Exemplo prático de uma requisição e resposta em JSON

De forma simplificada, vamos ilustrar uma requisição e uma resposta bem simples em JSON. No código abaixo, temos um cliente que realiza uma solicitação POST para o endpoint /api/v1/users. A solicitação é um objeto JSON, que requisita informações do usuário:

POST /api/v1/users HTTP/1.1
Authorization: Bearer 1234567890
Content-Type: application/json

{
"name": "John Doe",
"email": "johndoe@example.com",
"password": "password123"
}

Como há uma requisição, o servidor retorna como resposta HTTP 201 Created, informando que o usuário foi criado com sucesso. No corpo da resposta, podemos verificar que se trata de um objeto JSON, contendo as informações do usuário recém-criado. A resposta do servidor:

HTTP/1.1 201 Created
Content-Type: application/json

{
"id": 1,
"name": "John Doe",
"email": "johndoe@example.com",
"created_at": "2023-03-08T12:00:00Z"
}

Caso de API’s que se beneficia do uso de JSON nas API’s

No exemplo simplificado abaixo, temos uma API em Java que utiliza o JSON. Trata-se de um API de gerenciamento de tarefas, cujos dados são transmitidos no formato JSON. A biblioteca utilizada é a Jackson para manipular JSON em Java.

A Classe Tarefa:

public class Task {
  private String id;
  private String description;
  private boolean completed;

  // Construtores, getters e setters
  // Exemplo de código JSON:
  // {
  //   "id": "1",
  //   "description": "Fazer compras",
  //   "completed": false
  // }
}

A classe ControleDeTarefas:

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.core.JsonProcessingException;
import spark.Request;
import spark.Response;
import spark.Route;

public class TaskController {
  private ObjectMapper objectMapper;
  private TaskService taskService;
  public TaskController(TaskService taskService) {
      this.taskService = taskService;
      this.objectMapper = new ObjectMapper();
  }
 
  public Route getAllTasks = (Request request, Response response) -> {
      response.type("application/json");
     return objectMapper.writeValueAsString(taskService.getAllTasks());
        }; 
    
        public Route createTask = (Request request, Response response) -> {
            response.type("application/json");
            Task task = objectMapper.readValue(request.body(), Task.class);
            taskService.createTask(task);
            response.status(201); // Created
            return objectMapper.writeValueAsString(task);
        };
    }

Na classe acima, foi utilizado o “ObjectMapper” para que seja possível converter objetos Java e JSON. Com o método “getAllTasks”, é possível obtermos todas as tarefas em formato JSON usando o método “objectMapper.writeValueAsString()”.

O método “createTask” lê o JSON recebido na requisição usando o método “objectMapper.readValue()”, que seguidamente criamos a tarefa chamando o método “taskService.createTask()”.

No fim, na configuração e inicialização da API, utilizamos o framework Spark Java:

import static spark.Spark.*;

public class TaskAPI {
  public static void main(String[] args) {
      TaskService taskService = new TaskService();
      TaskController taskController = new TaskController(taskService);

      // Configuração das rotas da API
      get("/tasks", taskController.getAllTasks);
      post("/tasks", taskController.createTask);
  }
}

Com o trecho de código acima, as rotas “/tasks” são configuradas para as ações de obter as tarefas e criar uma nova.

Utilizando ferramentas como a cURL, Postman, por exemplo, podemos criar uma nova tarefa fazendo uma requisição POST para “http://localhost:4567/tasks”, informando o seguinte:

{
"id": "1",
"description": "Fazer compras",
"completed": false
}

E assim, exemplificamos de forma reduzida a comunicação entre clientes e servidores utilizando o formato JSON. Isso pode ser ampliado a depender da necessidade de cada API e dos usuários.

CONSIDERAÇÕES FINAIS

Em conclusão, constatamos que o uso do JSON nas API’s é uma combinação poderosa. Essa combinação culmina em uma série de benefícios e vantagens para os desenvolvedores de aplicativos e sistemas.

Como o JSON é uma estrutura de dados simplificada, a sua compreensão e manipulação dos dados se torna mais fácil para os indivíduos que estão desenvolvendo as mais diversas aplicações. Além de ser eficiente na transmissão dos dados.

Outro ponto salutar da utilização do JSON é a sua flexibilidade para evolução e escalabilidade, pois os arquivos de dados podem requer que os campos sejam atualizados, com inserção ou remoção de alguns campos. Esse processo acaba não atrapalhando no funcionamento das API’s que já os utilizam.

Os desenvolvedores de API’s precisam explorar todo o potencial dessa aliança poderosa entre o JSON e as API’s. Enquanto desenvolvedores, devemos criar aplicativos inovadores e sistemas integrados, que retirem todo o potencial da simplicidade e flexibilidade do JSON.

De olho no futuro, fica cada vez mais evidente o papel fundamental das API’s e do JSON enquanto linguagem universal da comunicação. Dessa forma, à medida que avançamos, novas potencialidades e funcionalidades devem originar a partir desta doce harmonia.

REFERÊNCIAS

[1] SMITH, B. Beginning JSON. Learn the preferred data format of the web. New York: Apress, 2015.

[2] CROCKFORD, D. The application/json Media Type for JavaScript Object Notation (JSON). 2006. Disponível em <https://datatracker.ietf.org/doc/html/rfc4627>. Acesso em: 11 jul 2023.

[3] BRAY, T. The JavaScript Object Notation (JSON) Data Interchange Format. Google, Inc. 2014. Disponível em <https://datatracker.ietf.org/doc/html/rfc7159>. Acesso em: 11 jul 2023.

[4] OLUWATOSIN, H. S. Client-Server Model. IOSR Journal of Computer Engineering. vol. 16, nº 1, fev 2014. ISSN: 2278-0661.