API: A ponte digital

Conteúdo deste artigo:

Introdução
Visão geral API
Implementação API
Conclusão
Referências

1. Introdução

A maior ponte da América Latina fica no Brasil, é a famosa ponte Rio-Niterói [1], por ela passam milhares de veículos todos os dias, esta ponte conecta Niterói ao Rio de Janeiro, permitindo que as pessoas que moram em Niterói e nos arredores acessem recursos do Rio de Janeiro e vice versa.

De acordo com o dicionario uma ponte é obra construída para estabelecer comunicação entre dois pontos separados por um curso de água ou qualquer depressão do terreno. Isso te lembra alguma coisa? Isso mesmo a API, no mundo virtual a API é a ponte que conecta dois pontos.

Mais do que dois pontos, as APIs permitem que componentes de software se comuniquem usando um conjunto de definições e protocolos [2], isso da a capacidade que as aplicações precisam para poder estabelecer uma comunicação entre si, usando solicitações e respostas.

É uma verdadeira ponte digital, na ponte da vida real, não importa se o carro é azul, verde, se foi fabricado por A ou por B, a ponte foi construida para permitir que eles a usem para acessar o outro lado, com a API não é diferente.

A diferença é que em vez de veículos, passam dados, e em vez de concreto e aço, nas APIs temos comandos, funções e protocolos.

Na ponte também temos regras, um carro sem placa por exemplo não vai conseguir passar, e nas APIs também temos regras, que como na ponte, servem para garantir uma comunicação segura com o outro lado.

Assim uma API é como uma ponte, que é formada por um conjunto de serviços/funções permite que programas/aplicativos possam utiliza-la para acessar recursos dos programas/aplicativos que forceram a ponte, tudo isso de forma simples, não se envolvendo em detalhes da implementação.

2. Visão geral API

Uma API(Application Programming Interface) pode ser bastante complexa de se entender sem compreender algumas palavras-chave, por isso abaixo listo algumas palavras-chave importantes:

API (Application Programming Interface): Uma interface de programação de aplicativos é um conjunto de regras e protocolos que permite que diferentes softwares se comuniquem e interajam entre si.

Endpoint: Um endpoint é uma URL específica em um servidor ou serviço que pode ser acessado por uma API. Cada endpoint geralmente representa uma funcionalidade ou recurso específico fornecido pela API.

Rota: Uma rota em uma API define um caminho específico que corresponde a um endpoint. É a combinação de um método HTTP e uma URL que direciona uma requisição para um determinado recurso ou ação.

Request (Requisição): É uma mensagem enviada por um cliente para um servidor, geralmente por meio de uma API, solicitando uma ação ou acesso a um determinado recurso.

Response (Resposta): É a mensagem enviada pelo servidor em resposta a uma requisição do cliente. A resposta geralmente contém os dados solicitados ou uma confirmação do sucesso ou falha da requisição.

Método HTTP: Representa a ação a ser realizada em um recurso específico. Os métodos HTTP mais comuns são GET (para obter dados), POST (para enviar dados), PUT (para atualizar dados) e DELETE (para excluir dados).

Autenticação: É o processo de verificação da identidade de um usuário ou aplicativo que está tentando acessar uma API. A autenticação pode ser feita por meio de chaves de API, tokens de acesso, login e senha, entre outros métodos.

Formato de dados: Refere-se à estrutura em que os dados são trocados entre o cliente e o servidor. Os formatos de dados comuns em APIs são JSON (JavaScript Object Notation) e XML (Extensible Markup Language).

Rate limiting: É uma técnica utilizada para limitar o número de requisições que um cliente pode fazer a uma API em um determinado período de tempo. Isso ajuda a evitar sobrecargas no servidor e a garantir uma distribuição justa dos recursos.

Versionamento: À medida que uma API evolui, é comum introduzir mudanças em sua estrutura e comportamento. O versionamento permite que diferentes versões da API coexistam, permitindo que os clientes continuem usando a versão anterior enquanto migram gradualmente para a nova versão.

Documentação: A documentação de uma API fornece informações detalhadas sobre como usá-la, incluindo descrições de cada endpoint, parâmetros de requisição, formatos de dados esperados e exemplos de código. A documentação é essencial para ajudar os desenvolvedores a entender e utilizar corretamente a API.

Com isso podemos ter uma visão geral do que é uma API, esta ponte digital construida com alguns conjuntos de regras e protocolos transforma a maneira de se pensar programação, pois se quisermos que nossos sistemas alcançem todo seu potencial precisamos de API.

Já dominamos o conceito, agora vamos avançar e verificar a evolução desta ponte digital, para se construir uma ponte forte e util precisamos seguir algumas regras certo? Com uma API não é diferente, ela precisa ser escalável, interoperável e de fácil manutenção.

Para isso será preciso seguir um estilo de arquitetura baseado em alguns princípios, e o nome para isso é API RESTful (Representational State Transfer) que é um estilo de arquitetura para o desenvolvimento de APIs, baseado nos princípios do protocolo HTTP.

Criar uma API seguindo o estilo API RESTful faz com que nossa ponte digital seja forte e consistente, pois toda sua construção é baseada em uma série de regras e princípios que garantem que ela seja fácil de usar e bem documentada, permitindo uma integração mais eficiente entre diferentes sistemas e aplicações.

A representational state transfer (REST – transferência de estado representacional) é uma arquitetura de software que impõe condições sobre como uma API deve funcionar. A REST foi criada inicialmente como uma diretriz para gerenciar a comunicação em uma rede complexa como a internet. [3]

Aqui estão algumas características e conceitos-chave associados a uma API RESTful:

Recursos (Resources): Uma API RESTful modela as informações e funcionalidades como recursos, que são objetos ou entidades do domínio de uma aplicação. Cada recurso é identificado por um URI (Uniform Resource Identifier) exclusivo, como /users ou /products.

Arquitetura cliente-servidor: indica uma arquitetura baseada em clientes, servidores e recursos, em que as solicitações são feitas via protocolo HTTP.

Cache: uma API REST deve ser desenvolvida de modo que consiga armazenar dados em cache. Quando uma informação fica armazenada em cache, as solicitações e respostas entre cliente e servidor são otimizadas.

Sistema de camadas: cada camada do sistema deve possuir uma funcionalidade específica (como segurança ou carregamento). Assim, cada camada é responsável por uma etapa diferente dos processos de requisição de usuário e de resposta do servidor

Os principais métodos HTTP: GET: Recuperar um recurso ou uma lista de recursos. POST: Criar um novo recurso. PUT: Atualizar completamente um recurso. PATCH: Atualizar parcialmente um recurso. DELETE: Remover um recurso.

Representações (Representations): Os recursos em uma API RESTful podem ter várias representações, como JSON, XML ou outros formatos. A escolha da representação é definida através do cabeçalho Content-Type nas requisições e respostas.

URI (Uniform Resource Identifier): Cada recurso na API RESTful é identificado por uma URI única. Essa URI deve ser consistente, estável e expressiva, seguindo as melhores práticas de design de URIs.

Estado (Stateless): Uma API RESTful é stateless, o que significa que cada requisição feita para a API contém todas as informações necessárias para ser processada. A API não mantém nenhum estado de sessão entre as requisições do cliente, facilitando a escalabilidade e a distribuição do sistema.

HATEOAS (Hypermedia as the Engine of Application State): É um princípio em que a API RESTful fornece links e informações de navegação junto com as respostas para permitir a descoberta dinâmica de recursos relacionados. Isso permite que os clientes da API naveguem e interajam com a API de forma mais flexível, sem a necessidade de conhecer todas as URLs de antemão.

Códigos de Status (Status Codes): Os códigos de status do protocolo HTTP são usados para indicar o resultado de uma requisição. Alguns exemplos comuns incluem 200 OK (requisição bem-sucedida), 201 Created (recurso criado com sucesso), 400 Bad Request (requisição inválida) e 404 Not Found (recurso não encontrado).

Este é um tipo de API, existem outros como APIs Web, APIs SOAP e etc; Como na construção de uma ponte real temos diversas formas de se contruir a famosa ponte digital chamada API, cada forma tem suas vantagens e desvantagens, mais o importante é que todas elas levam a construção de algo incrível.

As APIs trazem muitos beneficios, como reutilização de código e funcionalidades, facilitação da integração de sistemas, modularização e separação de responsabilidades, aceleração do desenvolvimento de aplicativos e facilidade de manutenção e evolução.

Uma API é a ponte digital que conecta ideias e soluções, transformando o potencial em realidade, permitindo que a inovação flua livremente.

3. Implementação API

A implementação de APIs envolve o uso de diversas ferramentas e tecnologias, pode ser tão complexo como a construção de uma ponte, como a ponte Rio-Niterói por exemplo, é preciso dominar os conceitos e seguir algumas regras e boas práticas para garantir que nossa ponte seja segura e funcional.

Para o nosso exemplo vamos usar o Java, Java é uma linguagem de programação orientada a objetos desenvolvida na década de 90 por uma equipe de programadores chefiada por James Gosling, na empresa Sun Microsystems, que em 2008 foi adquirido pela empresa Oracle Corporation. [4]

Tecnologias utilizadas:

Spring Boot: Um framework do ecossistema Spring que facilita a criação de aplicativos Java autônomos, incluindo APIs. O Spring Boot simplifica a configuração e o gerenciamento de dependências, facilitando assim o desenvolvimento das funcionalidades da API.

Spring MVC: Uma parte do Spring Framework que fornece suporte para desenvolvimento de aplicações web, incluindo a criação de APIs RESTful. O Spring MVC oferece recursos como mapeamento de rotas, gerenciamento de requisições e respostas, validação de dados, entre outros.

Hibernate: Uma biblioteca ORM (Object-Relational Mapping) que simplifica a interação com bancos de dados relacionais. O Hibernate permite que se defina as entidades de domínio em Java e mapeie-as para tabelas do banco de dados, fornecendo uma camada de abstração para persistência de dados.

É importante compreender também o que são as entidades, os repositorios e os controladores: as entidades representam os objetos de negócio, os repositórios fornecem acesso e manipulação de dados e os controladores lidam com a recepção e o processamento das requisições HTTP na API.

Vamos desenvolver uma API de gerenciamento de tarefas, onde os usuários podem criar, atualizar, buscar e excluir tarefas. Vamos seguir os passos abaixo para implementar essa API:

Passo 1: Configuração do projeto

Vamos começar criando um novo projeto Spring Boot. Podemos usar ferramentas como Spring Initializr ou criar manualmente um projeto Maven ou Gradle. É necessário adicionar as dependências necessárias, como Spring Web, Hibernate e outras dependências relevantes ao projeto.

Passo 2: Definindo as entidades

As entidades representam objetos do domínio de negócio da aplicação. Elas encapsulam os dados e o comportamento relacionados a um conceito específico do sistema.

No contexto de um banco de dados relacional, as entidades são mapeadas para tabelas e fornecem uma representação da estrutura e das relações de dados.

Vamos criar as entidades de domínio para a API, como “Task” e “User”. Anote as entidades com as anotações apropriadas, como @Entity, @Table e @Id, para mapeá-las corretamente no banco de dados.


@Entity
@Table(name = "tasks")
public class Task {
  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  private Long id;
  
  @Column(nullable = false)
  private String title;
  
  @Column(nullable = false)
  private String description;
  
  // getters e setters
}

@Entity
@Table(name = "users")
public class User {
  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  private Long id;
  
  @Column(nullable = false)
  private String name;
  
  // getters e setters
}

Passo 3: Criação dos repositórios

Os repositórios são responsáveis por abstrair o acesso e a manipulação de dados de uma entidade específica. Eles fornecem métodos para realizar operações de leitura, escrita, atualização e exclusão (CRUD) no banco de dados relacionado à entidade.

Agora vamos criar as interfaces de repositório para interagir com o banco de dados. Utilize o Hibernate e o Spring Data JPA para facilitar a implementação dos métodos CRUD (Create, Read, Update, Delete).


public interface TaskRepository extends JpaRepository<Task, Long> {
}

public interface UserRepository extends JpaRepository<User, Long> {
}

Passo 4: Definindo os controladores

Os controladores são responsáveis por receber e processar as requisições HTTP na API. Eles atuam como intermediários entre as requisições feitas pelos clientes e as operações a serem realizadas nos dados.

Também vamos criar controladores para manipular as requisições HTTP da API. Anote os métodos com as anotações adequadas, como @RestController, @RequestMapping, @GetMapping, @PostMapping, @PutMapping, @DeleteMapping, entre outras.

@RestController

@RequestMapping("/api/tasks")

public class TaskController {

  private final TaskRepository taskRepository;
  
  public TaskController(TaskRepository taskRepository) {
      this.taskRepository = taskRepository;
  }
  
  @GetMapping
  public List<Task> getAllTasks() {
      return taskRepository.findAll();
  }
  
  @GetMapping("/{id}")
  public ResponseEntity<Task> getTaskById(@PathVariable Long id) {
      Optional<Task> task = taskRepository.findById(id);
      if (task.isPresent()) {
          return ResponseEntity.ok(task.get());
      } else {
          return ResponseEntity.notFound().build();
      }
  }
  
  @PostMapping
  public Task createTask(@RequestBody Task task) {
      return taskRepository.save(task);
  }
  
  @PutMapping("/{id}")
  public ResponseEntity<Task> updateTask(@PathVariable Long id, @RequestBody Task taskDetails) {
      Optional<Task> optionalTask = taskRepository.findById(id);
      if (optionalTask.isPresent()) {
          Task task = optionalTask.get();
          task.setTitle(taskDetails.getTitle());
          task.setDescription(taskDetails.getDescription());
          return ResponseEntity.ok(taskRepository.save(task));
      } else {
          return ResponseEntity.notFound().build();
      }
  }
  
  @DeleteMapping("/{id}")
  public ResponseEntity<Void> deleteTask(@PathVariable Long id) {
      Optional<Task> optionalTask = taskRepository.findById(id);
      if (optionalTask.isPresent()) {
          taskRepository.deleteById(id);
          return ResponseEntity.noContent().build();
      } else {
          return ResponseEntity.notFound().build();
      }
  }
}

Passo 5: Definindo endpoints e rotas

No nosso exemplo, estamos utilizando a anotação @RequestMapping na classe TaskController para especificar o prefixo /api/tasks para todos os endpoints relacionados a tarefas. Cada método do controlador é mapeado para uma rota específica, que define a ação a ser realizada no recurso.

O método getAllTasks() é mapeado para a rota GET /api/tasks, que retorna todas as tarefas existentes. O método getTaskById(Long id) é mapeado para a rota GET /api/tasks/{id}, que retorna uma tarefa específica com o ID fornecido.

Os outros métodos seguem um padrão semelhante para as operações de criação, atualização e exclusão de tarefas.

Através da anotação @PathVariable, podemos extrair valores da URL e usá-los como parâmetros nos métodos. Por exemplo, o parâmetro id no método getTaskById(Long id) é extraído da rota e utilizado para buscar a tarefa correspondente no repositório.

Passo 6: Documentação da API

Até aqui já conseguimos ver teoria e prática de alguns conceitos inerentes a uma API Java, podemos percerber que nosso ponte digital, quando construida em Java depende de muitas tecnologias para funcionar da maneira que precisamos.

Com isso em mente, uma API pode se tornar muito complexa de se manter e fazer manutenção, por isso uma parte importante deste processo é a documentação.

A documentação adequada de uma API é essencial para facilitar o uso e entendimento por parte dos desenvolvedores. Uma opção popular para documentar APIs em Java é utilizar o Swagger, uma ferramenta que gera uma documentação interativa a partir dos metadados da API.

Para adicionar suporte ao Swagger, podemos adicionar a dependência springfox-swagger2 ao nosso projeto e criar uma configuração para habilitar o Swagger e definir os detalhes da documentação.

@Configuration

@EnableSwagger2

public class SwaggerConfig {

  @Bean
  
  public Docket api() {
  
      return new Docket(DocumentationType.SWAGGER_2)
              .select()
              .apis(RequestHandlerSelectors.basePackage("com.example.api"))
              .paths(PathSelectors.any())
              .build();
  }
}

Depois de configurado, podemos acessar a documentação gerada pelo Swagger por meio de um navegador, geralmente em http://localhost:8080/swagger-ui.html. Lá, vamos encontrar informações detalhadas sobre os endpoints, parâmetros, respostas e exemplos de uso da API.

E é isso, este foi um pequeno exemplo de construção de uma API (ponte digital) feita em Java, mostramos como implementar uma API usando Java, Spring Boot, Spring MVC e Hibernate.

Também Definimos as entidades, criamos repositórios, controladores e utilizamos anotações para mapear os endpoints e rotas. Além de mencionar a importância da documentação e apresentamos o Swagger como uma opção para documentar a API.

A partir daqui, seria possivel continuar construindo mais endpoints, adicionar autenticação, implementar validações e adicionar outros recursos conforme necessário para atender aos requisitos da aplicação.

É importante dizer que apesar de poder construir esta API usando um unico arquivo para uma melhor compreensão e para fins de estudo e prática, o ideal é que o código seja organizado em uma etrutura apropriada.

A estrutura correta é aquela onde cada classe (entidades, repositórios, controladores) estaria em seu próprio arquivo. Além disso, a configuração do Swagger e outras configurações também seriam separadas em arquivos apropriados.

Este foi um exemplo de implementação de uma API feita em Java, mas existem muitas outras tecnologias disponíveis para implementar APIs, cada uma com suas vantagens e casos de uso específicos. Abaixo listo algumas delas:

Node.js: Uma plataforma de tempo de execução JavaScript que permite construir APIs escaláveis e de alto desempenho. Com a ampla adoção do JavaScript no desenvolvimento web, o Node.js se tornou uma escolha popular para criar APIs rápidas e eficientes.

Django: Um framework em Python que facilita o desenvolvimento rápido de APIs. O Django oferece recursos abrangentes para lidar com autenticação, roteamento, serialização de dados e muito mais, tornando-o uma escolha sólida para criar APIs robustas e seguras.

Ruby on Rails: Um framework em Ruby que segue o paradigma “convenção sobre configuração”. O Rails fornece uma estrutura completa para construir APIs RESTful de forma eficiente, com uma sintaxe limpa e concisa.

Express.js: Um framework minimalista e flexível para Node.js que permite criar APIs de forma simples e rápida. O Express.js fornece uma camada fina de abstração sobre o Node.js, facilitando a criação de rotas, tratamento de requisições e respostas, além de integração com middlewares.

Assim podemos percerber que construir esta famosa ponte digital não é uma coisa simples, é preciso dominar muitos conceitos e seguir boas práticas de design, manter a segurança da API e garantir que ela seja fácil de usar e entender para os desenvolvedores que a consomem.

4. Conclusão

Assim chegamos ao fim de mais um artigo, a API(Interface de Programação de Aplicação) é realmente uma grande inovação, mesmo que este conceito esteja presente desde os primórdios da computação, as APIs estão mais presentes do que nunca, servindo de ponte para a inovação.

Assim como a ponte Rio-Niterói transformou a vida das pessoas que moram no estado Rio de Janeiro, trazendo agilidade, permitindo o compartilhamento de recursos de forma mais fácil, as APIs são a ponte que permitiram a evolução da maioria das inovações e tecnologias que existem hoje.

O nascimento da API que conhecemos hoje foi durante o evento IDG Demo 2000, quando o Salesforce, software de CRM, lançou sua primeira API em 7 de Fevereiro de 2000 feita em XML. [5]

A Salesforce identificou a necessidade de seus clientes em compartilhar dados através de diferentes aplicações que usavam e a API foi o caminho para isso acontecer. [5]

Percebe? Se identifica uma necessidade de compartilhar recursos, se implementa uma API que é a ponte e assim se inicia a maior revolução do mundo digital, a era das APIs se inicia, facilitando a criação de novos serviços e modelos de negócios.

Mas elas precisam ser bem projetadas e implementadas, por isso surgem as melhores práticas, definem-se regras, diretrizes e assim surgem diferentes tipos de APIs, sendo necessário escolher a melhor forma de construir sua “ponte” para atender as necessidades especificas do seu negócio.

Hoje temos um mundo digital gigantesco e cheio de pontes digitais, as APIs são estas pontes digitais que conectam aplicativos e possibilitam a inovação em uma escala sem precedentes. São como blocos de construção mágicos que formam as pontes que permitem que aplicativos se comuniquem.

5. Referências

[1] A maior ponte https://www.karvi.com.br/blog/maiores-pontes-mundo-veja-top-5/ Acessado em 11/07/2023

[2] O que é uma API https://aws.amazon.com/pt/what-is/api/ Acessado em 11/07/2023

[3] Restful api https://aws.amazon.com/pt/what-is/restful-api/ Acessado em 11/07/2023

[4] Java https://pt.wikipedia.org/wiki/Java_(linguagem_de_programa%C3%A7%C3%A3o) Acessado 12/07/2023

[5] API https://mundoapi.com.br/materias/uma-breve-historia-das-apis-com-a-pluga/ Acessado 12/07/2023

Criando uma API REST com o Spring Boot https://www.treinaweb.com.br/blog/criando-uma-api-rest-com-o-spring-boot Acessado 12/07/2023

Construindo uma API RESTful com Java e Spring Framework https://mari-azevedo.medium.com/construindo-uma-api-restful-com-java-e-spring-framework-46b74371d107 Acessado 12/07/2023

Guia do Spring Framework: Spring Boot, Spring MVC, Spring REST, JPA, Hibernate, Spring Security https://guilherme-manzano.medium.com/guia-do-spring-framework-spring-boot-spring-mvc-spring-rest-jpa-hibernate-spring-security-6476ca4dbe13 Acessado 12/07/2023