<<Desafiando seus limites: O enigma das APIs.>>

#API Rest

- Meu nome é Icaro d. Paula e vou introduzir a vocês o mundo das APIs. Caso você seja iniciante, não se preocupe, explicarei de forma clara e simples.

Para muitos programadores, este assunto pode parecer um tanto desafiador, nesse artigo iremos destrinchar conceitos básicos e buscar a compreensão absoluta dos temas a serem abordado.

O que veremos nesse artigo:

o que é e para que serve uma API;
como funcionam as APIs;
o que são endpoints e rotas de uma api;
o que é formato JSON;
manipulação de JSON;
o que é uma API RESTful.

1. O que é e para que serve uma api.

Imagine que diferentes softwares precisam se comunicar entre si, de uma forma pela qual os mesmos possam interagir, compartilhar informações e realizar tarefas específicas, é onde encaixamos as APIs "Application Programing Interface".

Podemos dizer que é um conjunto de protocolos, com a função de servir como contrato, esse contrato que vai dizer como as aplicações devem se comportar ao conversar com os demais.

1.1 Por quê utilizar em seus projetos?

A vantagem de utilizar APIs é que elas vão estar facilitando a integração de vários sistemas, ou seja, seus softwares podem estar acessando recursos, e trocar informações externas de forma padronizada.

Em resumo, são como intermediadoras que permitem que os softwares conversem entre si, facilitadores que permitem que sua aplicação se conecte a serviços externos e troque dados de maneira eficiente

2. Como funcionam as APIs.

As APIs possuem "endpoints", são como URLs que você utiliza para acessar seus recursos ou realizar ações, quando feita uma solicitação para um desses, o server da API busca entregar uma resposta ao que você está pedindo.

Vamos supor uma aplicação que indica o clima da sua região, para saber a temperatura de onde você está localizado, esse aplicativo faz uma solicitação para uma API de clima, transferindo essa localização.

A API recebe esses dados e devolve uma resposta com a temperatura atual para a aplicação, é assim que a mágica ocorre.

2.1 Como esses sistemas conversam entre si?

Utilizando protocolos de comunicação, como por exemplo o HTTP, o cliente pode ser uma aplicação ou um Website, pode fazer essa solicitação usando um protocolo para a endpoint da API, após o processamento desses dados, ela devolve uma resposta no mesmo formato.

3. O que são endpoints e rotas de uma API.

Vamos imaginar que endpoints e rotas são como mapas que acompanham as solicitações até o encontro de recursos ou a realização de ações.

Como explicado anteriormente, os endpoints são URLs especiais que as APIs nos disponibilizam, da endpoint pode representar uma função, ou um conjunto de ações.

Por exemplo, ao utilizar uma aplicação de músicas, teremos uma endpoint para encontrar informações de determinada música, outro para listar as mais populares, e assim por diante.

Agora, podemos dizer que as rotas são como o sistema de roteamento das APIs. Elas que definem os caminhos das (URLs).

Se temos uma endpoint que busca informações sobre determinada música, a rota poderia ser escrita como: "/musica/informacoes", para adicionar uma música a lista de reprodução poderia ser: "adicionar/lista/reproducao".

from flask import Flask, request, jsonify

app = Flask(__name__)

# Lista de reprodução (apenas para fins de demonstração)
playlist = []

@app.route('/api/playlist/add', methods=['POST'])
def add_to_playlist():
  # Obtém os dados da música do corpo da solicitação em formato JSON
  data = request.get_json()

  # Verifica se todos os campos necessários estão presentes na solicitação
  if 'title' not in data or 'artist' not in data:
      return jsonify({'error': 'Dados incompletos. Certifique-se de incluir o título e o artista da música.'}), 400

  # Extrai os campos da música
  title = data['title']
  artist = data['artist']

  # Cria um dicionário para representar a música
  song = {'title': title, 'artist': artist}

  # Adiciona a música à lista de reprodução
  playlist.append(song)

  return jsonify({'message': 'Música adicionada à lista de reprodução com sucesso.'}), 200

if __name__ == '__main__':
  app.run()

Como visto no exemplo acima, as rotas especificam as operações nos HTTP que vamos executar nas endpoints. Há varias opções de operações como GET, POST, PUT e DELETE, na mesma ordem, para puxar informações, enviar dados, atualizar as informações e deletar dados.

4. O que é formato JSON?

Podemos descrever como uma linguagem de dados que "todos" entendem. Quando esses diferentes sistemas precisam comunicar entre si, utilizamos o JSON(Javascript Object Notation) que é um arquivo leve e de fácil compreensão para representar nossos dados.

Sendo uma alternativa popular ao XML, ele é baseado na sintaxe de objetos do Javascript, sua estrutura é bem simples, os dados são organizados em palavras chave, a chave é uma palavra que identifica o dado, como um nome.

Por exemplo, podemos ter um par com "nome" e "Pedro", em que o valor correspondente é "Pedro" e a chave é "nome".

{
"nome": "Pedro"
}

O formato de arquivo JSON suporta muitos tipos de dados, como strings, números, booleanos e arrays, em resumo é uma linguagem para representar dados estruturados.

5. Manipulação de JSON

Em seu sentido literal, a manipulação de JSON significa ler e escrever dados no formato JSON, em linguagens como java, existem bibliotecas que facilitam essa conversão entre objetos java e JSON.

Vamos supor que você possui um objeto em java e precisa converter em JSON para compartilhar com outros softwares.

import com.fasterxml.jackson.databind.ObjectMapper;

public class ObjectToJsonConverter {
  public static void main(String[] args) {
      // Criar um objeto Java para converter em JSON
      Person person = new Person("John Doe", 30, "john.doe@example.com");

      // Criar um objeto ObjectMapper (da biblioteca Jackson)
      ObjectMapper objectMapper = new ObjectMapper();

      try {
          // Converter o objeto Java para JSON
          String json = objectMapper.writeValueAsString(person);

          // Imprimir o JSON resultante
          System.out.println(json);
      } catch (Exception e) {
          e.printStackTrace();
      }
  }
}

class Person {
  private String name;
  private int age;
  private String email;

  public Person(String name, int age, String email) {
      this.name = name;
      this.age = age;
      this.email = email;
  }

  // getters e setters (necessários para a biblioteca Jackson)

  public String getName() {
      return name;
  }

  public void setName(String name) {
      this.name = name;
  }

  public int getAge() {
      return age;
  }

  public void setAge(int age) {
      this.age = age;
  }

  public String getEmail() {
      return email;
  }

  public void setEmail(String email) {
      this.email = email;
  }
}

As bibliotecas Gson e Jackson podem auxiliar o processo, pois elas oferecem métodos que facilitam essa conversão, as mesmas bibliotecas podem ser úteis para a conversão de JSON para java.

Possuem métodos que transformam a string JSON para um objeto java estruturado, permitindo que você manipule os dados em seu código.

6. O que é uma API RESTful.

API RESTful é uma forma especial de projetar as APIs, seguindo os princípios da arquitetura REST, que é uma forma inteligente de organizar as informações.

Essa forma utiliza verbos HTTP para representar as ações, são as operações CRUD que são respectivamente:

GET/Create(criar)
POST/Read(ler)
PUT/Update(atualizar)
DELETE/Delete(apagar)

também usa recursos do servidor, são como as entidades que acessamos através das URLs, conhecido como endpoint.

Uma importante característica da API RESTful é que ela é stateless, ou seja, não armazena informações de estado entre suas solicitações, cada requisição é independente.

Contém as informações necessárias para que o servidor entenda o que está sendo pedido, isso aumenta a performance da comunicação entre os sistemas.

7. Conclusão

As APIs são como pontes que ligam diferentes tipos de softwares, pode ser criada com vários tipos de linguagens de programação, é fundamental para qualquer programador saber utilizar suas tecnologias, pois praticamente as APIs estão presente em tudo no seu dia a dia.

Sua documentação deve ser clara e objetiva, pois devemos possuir bons hábitos para facilitar sua implementação em nossos projetos, também aprendemos o funcionamento dos arquivos JSON sua versatilidade, leveza e simplicidade na hora de trabalhar com APIs, sua estrutura e como converter-los para java.