Introducao#

• Protocolo de aplicacao que serve para transferir informacoes entre cliente e servidor, chamado de HTTP ou Hyper Text Transfer Protocol;
• No modelo de camadas, o protocolo HTTP eh atribuido a camada 7 (aplicacao), e usa o protocolo TCP para estabelecer suas comunicacoes;
• Funciona sem criptografia e envia todas as informacoes em texto nao criptografado (seu irmao, “HTTPS”, faz o contrario e junta o poder do HTTP e do TLS/SSL) e eh stateless;
• URI (Uniform Resource Identifier) permite que o protocolo identifique qual recurso deve ser acessado (uma URL - Uniform Resource Locator - eh um exemplo de como ele faz isso);
  • A construcao de um URL da-se pelo conjunto dos seguintes elementos:
    • Scheme: instrui sobre qual protocolo usar para acessar o recurso, como HTTP, HTTPS, FTP;
    • User: alguns servicos exigem autenticacao para efetuar login, voce pode inserir um nome de usuário e uma senha na URL para efetuar login;
    • Host / Domain: o nome de dominio ou endereco IP do servidor que voce deseja acessar;
    • Port: a porta a qual você se conectara;
    • Path: o nome do arquivo ou local do recurso que você está tentando acessar;
    • Query String: bits extras de informacao que podem ser enviados para o caminho solicitado (ex: /blog?id=1);
    • Fragment: referencia a um local na pagina solicitada. Isso é comumente usado para páginas com conteudo longo e pode ter uma determinada parte da pagina diretamente vinculada a ela, para que fique visivel ao usuario assim que ele acessa a pagina (ex: #task1).
• Recebe um pedido (request) e responde-o (response);
• Sua estrutura eh a seguinte:
  • Request:
    • Metodo / Verbo;
    • Recurso;
    • Versao do Protocolo + Headers + Body.
  • Response:
    • Versao do Protocolo;
    • Status da Resposta;
    • Mensagem de Status + Headers + Body.
  • Podemos ter alguns tipos de headers, sao eles:
    • Gerais: aparecem tanto em requests quanto em responses, e nao estao relacionados ao conteudo da mensagem;
      • ex: Cache-Control.
    • De Requisicao: contem mais informacoes sobre a requisicao, seu cliente ou sobre o recurso solicitado;
      • ex: User-Agent, Accept.
    • De Resposta: fornecem informacoes adicionais sobre a resposta, como o seu local ou o seu servidor;
      • ex: Server, Set-Cookie;
      • Eh ideal ter cautela com esses headers, pois eles podem apresentar risco a seguranca;
      • Quando for usar o Set-Cookie, sempre se atente em utilizar as flags Secure (serao enviados apenas sobre HTTPS) e HttpOnly (para nao serem acessadas pelo javascript).
    • De Entidade: contem informacoes sobre o corpo da entidade, como seu tamanho ou seu tipo;
      • ex: Content-Type, Content-Length;
      • Os tipos de Content-type mais comuns sao:
        • URL Encoded (application/x-www-form-urlencoded);
        • Form Data (multipart/form-data);
        • JSON (application/json);
        • XML (application/xml).
    • De Seguranca: ajudam a melhorar a seguranca geral do app web, fornecendo mitigacoes contra ataques;
      • Content-Security-Policy (CSP):
        • Camada de segurança adicional que pode ajudar a mitigar contra ataques comuns, controlando o que pode ser executado dentro da pagina;
        • Fornece um caminho para administradores dizerem quais dominios ou recursos sao considerados seguros e prove uma camada de mitigacao para alguns ataques;
        • ex: Content-Security-Policy: default-src 'self'; script-src 'self' https://cdn.tryhackme.com; style-src 'self'
          • default-src: especifica a política padrão de si, o que significa apenas o site atual;
          • script-src: especificam a política de onde os scripts podem ser carregados;
          • style-src: especifica a política para as folhas de estilo CSS podem ser carregadas.
      • Strict-Transport-Security (HSTS):
        • Garante que o web browser sempre se conectara via HTTPS;
        • ex: Strict-Transport-Security: max-age=63072000; includeSubDomains; preload;
          • max-age: define o tempo de expiracao para essa configuracao;
          • includeSubDomains: configuracao opcional que instrui o browser para aplicar essa regra tambem nos subdominios;
          • preload: configuração opcional que permite que o site seja incluído nas listas de preload. Os navegadores podem usar listas de preload para aplicar os HSTS antes mesmo de fazer sua primeira visita a um site.
      • X-Content-Type-Options:
        • Pode ser usado para instruir os navegadores a não adivinhar o tipo MIME de um recurso, mas apenas usar o declarado no Content-Type;
        • ex: X-Content-Type-Options: nosniff;
          • nosniff: essa diretiva instrui o browser para nao sniffar o tipo MIME.
      • Referrer-Policy:
        • Controla a quantidade de informacoes compartilhadas sobre a pagina de origem (referenciador) enviadas ao servidor da Web de destino quando um usuario eh redirecionado do servidor de origem, bem como quando clica em um hiperlink;
        • Resumidamente, controla a privacidade e seguranca dos dados da URL de origem enviados em requisicoes subsequentes;
        • ex:
          • Referrer-Policy: no-referrer: desabilita completamente qualquer informacao enviada sobre o referenciador;
          • Referrer-Policy: origin: envia apenas o dominio;
          • Referrer-Policy: same-origin: enviara apenas informacoes do referenciador quando o destino fizer parte da mesma origem (mesmo dominio);
          • Referrer-Policy: strict-origin:  envia apenas o referenciador como origem quando o protocolo permanece o mesmo (HTTPS para HTTPS);
          • Referrer-Policy: strict-origin-when-cross-origin: envia a URL completa em navegações internas seguras, domínio apenas em externas, nada se for HTTPS para HTTP.

1
/** Request */
2
POST /uri HTTP/1.1
3

4
// @Headers
5
Host: example.com
6
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
7
Accept: application/json // "O que eu quero receber"
8
Content-Type: application/json // "Como eu esto enviando"
9
Content-Length: 50
10
// EMPTY LINE: separa o header do body!
11
// @Body
12
{
13
    "name": "John Doe",
14
    "email": "john.doe@example.com"
15
}
16

17
/** Response */
18
HTTP/1.1 201 Created // Eh chamado de `status line`
19

20
// @Headers
21
Date: Sat, 27 Jul 2024 12:28:53 GMT
22
Content-Type: application/json
23
Content-Length: 92
24
Location: /api/users/1
25

26
// @Body
27
{
28
    "id": 1,
29
    "name": "John Doe",
30
    "email": "john.doe@example.com",
31
    "createdAt": "2024-07-27T12:28:53Z"
32
}

Metodos / Verbos HTTP#

• Verbos / Metodos sao maneiras semanticas de dizer o que queremos fazer com a requisicao (no fundo todas funcionam da mesma maneira);
• Sao eles:
  • GET: solicitar conteudo;
  • HEAD: semelhante ao get, porem apenas os cabecalhos sao retornados;
  • POST: utilizado quando eh necessario enviar algo a ser processado;
  • PUT / PATCH / MERGE: utilizado para indicar alteracao de conteudo;
    • Put seria para alteracoes em massa (e caso ainda nao exista alguma das alteracoes, ele gera);
    • Patch para pequenas alteracoes.
  • DELETE: utilizado para indicar remocao de conteudo;
    • Nao aceita body portanto se precisar de dados dinamicos use queryStrings;
    • Para bulk delete use arrays na query.
  • OPTION: utilizado para saber quais operacoes de um determinado recurso estao disponiveis;
  • CONNECT: estabelece um tunelamento TCP / IP com o servidor, geralmente para facilicar a comunicacao SSL;
  • TRACE: envia um teste de loopback motrando o caminho que uma requisicao faz para chegar ate o recurso especificado no servidor destinado.

Respostas (Responses) HTTP#

• Existem 5 categorias, que estao localizadas nos ranges 1~5, onde de 1~3 sao informativos e de 4~5 sao erros.

Definicao#

• Significado:
  • Interface de Programacao de Aplicacoes;
  • Application Programming Interface.
• Sao mecanismos que permitem que dois componentes de software se comuniquem usando um conjunto de definicoes e protocolos;
• Tambem pode ser vista como um contrato de servico entre duas aplicacoes.

Funcionamento#

• Funcionam com base nas comunicacoes cliente e servidor;
• Existem quatro maneiras diferentes pelas quais as APIs podem funcionar, dependendo de quando e por que elas foram criadas. Sao elas:
  • SOAP:
    • Usam o Simple Object Access Protocol;
    • O cliente e servidor trocam mensagens usando XML;
    • Esse design eh menos flexivel e era mais popular no passado.
  • RPC:
    • Conhecidas como Remote Procedure Calls;
    • O cliente conclui uma funcao / procedimento no servidor e o servidor envia a saida de volta ao cliente.
  • WebSocket:
    • Usa objetos JSON para transmitir dados;
    • Oferece suporte a comunicacao bidirecional entre aplicativos cliente-servidor;
    • O servidor pode enviar mensagens de retorno de chamada a clientes conectados, tornando-o mais eficiante que o design REST.
  • REST:
    • Sao as mais populares e flexiveis atualmente;
    • O cliente envia solicitacoes ao servidor como dados e o servidor usa essa entrada do cliente para iniciar funcoes internas e retornar os dados de saida ao cliente.

Autenticacao#

Construindo uma API Rest#

Boas Praticas para Construcao de APIs#

• Utilize o mesmo padrao de URI na identificacao dos recursos;
• Deixe facil o processo de versionamento;
• Para nomear, utilize substantivos no plural, evite verbos (ja que URIs representam recursos e nao acoes) e use hifens junto de letras minusculas;
• Se atente ao contexto para usar o verbo HTTP correto;
• Evite adicionar na URI a operacao a ser realizada no recurso;
• Evite adicionar na URI o formato desejado da representacao do recurso;
  • Suporte diferentes representacaos (HTML, XML, JSON, etc).
• Evite manter dados de autenticacao / autorizacao em sessao, para isso use:
  • OAUTH, JWT, Keycloack, etc.
• Tente utilizar, no maximo, 3 niveis de acoes;
• Utilize acoes apenas apos definir uma URI para um resource, desde que a acao nao sobrescreva o sentido do verbo HTTP;
• Evite fazer com que o patch explique o da hierarquia anterior;
  • ex: POST /usuarios/criar;
    • Neste caso basta o verbo HTTP: POST /usuarios.
• Filtros sempre na queryString, e nunca deve ser colocado como parametro / parte da rota;
• Ordene endpoints por dependencia;
  • ex: /courses/1/topics/1/class;
    • Courses depende de topics que, por sua vez, depende de class.
• Para formatacao de data e hora use o padrao ISO 8601 e UTC.

Versionamento#

• Temos dois tipos de versionamento, sao eles:
  • URL:
    • Por Subdominio (ex: http://api-v1.minhaapi.com/vinhos);
    • Por Path (ex: http://minhaapi.com/v1/vinhos);
    • Por Querystring (ex: http://minhaapi.com/vinhos?version=1.0).
  • Header:
    • Via Accept (ex: Accept: application/vnd.gastronomia.v2+json);
    • Via Header Customizado (ex: api-version: 2);
      • Junto do Path eh a melhor combinacao;
      • Podemos fornecer uma data, por exemplo, e a partir dela pegar a minor atualizada.

Throttling, Rate Limiting e Outros Limitadores#

• Sao estrategias complementares, mas nao tem as mesmas funcoes.

Filtragem, Paginacao e Ordenacao de Consultas#

1
-- GET /api/products?category=books&author=John
2

3
SELECT * FROM products WHERE category = 'books' AND author = 'John';

1
-- Eq.: OFFSET = (current page - 1) * items per page
2

3
-- GET /api/products?per_page=10&page=1
4
SELECT * FROM products LIMIT 10 OFFSET 0;
5

6
-- GET /api/products?per_page=10&page=2
7
SELECT * FROM products LIMIT 10 OFFSET 10;
8

9
-- GET /api/products?per_page=10&page=3
10
SELECT * FROM products LIMIT 10 OFFSET 20;
11

12
-- ...

1
GET /api/products?since_id=100&max_id=200
2

3
> Retorna todos os produtos de ID 100 ate 200.

1
GET /api/products?page=3&page_size=10
2

3
> Retorna 10 produtos da pagina 3.

1
GET /api/products?offset=10&limit=30
2

3
> Retorna 30 produtos a partir do decimo registro.

1
-- GET /api/products?sort_by=author&order=desc
2

3
SELECT * FROM products ORDER BY author DESC;
4

5
-- GET /api/products?order=author:desc,price:asc,...
6

7
SELECT * FROM products
8
ORDER BY
9
  author DESC,
10
  price ASC,
11
  -- ...

1
/*
2
GET /api/products
3
  ?category=books
4
  &start_date=2025-01-01
5
  &end_date=2025-01-28
6
  &min_price=1000
7
  &max_price=2000
8
  &sort_by=author
9
  &order=desc
10
  &per_page=10
11
  &page=1
12
*/
13

14
SELECT *
15
FROM products
16
WHERE
17
  category = 'books'
18
  AND created_at BETWEEN '2025-01-01' AND '2025-01-28'
19
  AND price BETWEEN 1000 AND 2000
20
ORDER BY author DESC
21
LIMIT 10 OFFSET 0;

Cache#

• Estrutura computacional de armazenamento focada em manter copias de dados que sao acessados com frequencia;
• Vantagens:
  • Reducao da latencia de rede;
  • Reducao de carga de processamento dos servidores;
  • Otimizacao de tempo de resposta do client.
• Tipos:
  • Shared Cache: armazena respostas de servidores para reutilizacao entre diversos usuarios;
  • Private Cache: armazena respostas de servidores para reutilizacao de apenas um usuario.