S01L02 - URIs baseados em recursos

html

URIs Baseadas em Recursos: Um Guia Abrangente

Tabela de Conteúdo

Introdução
Compreendendo URIs Baseadas em Recursos
URIs Baseadas em Ações vs. URIs Baseadas em Recursos
Desenhando URIs Baseadas em Recursos Eficazes
Métodos HTTP em URIs Baseadas em Recursos
Códigos de Status HTTP Explicados
Implementando URIs Baseadas em Recursos: Um Exemplo Prático
Melhores Práticas e Convenções
Conclusão


Introdução
No âmbito do desenvolvimento web e do design de APIs, os Identificadores Uniformes de Recursos (URIs) desempenham um papel fundamental na definição de como os recursos são acessados e manipulados. Este eBook aprofunda-se nas URIs baseadas em recursos, um conceito fundamental na criação de APIs RESTful que são intuitivas, escaláveis e de fácil manutenção.
Compreender as URIs baseadas em recursos é essencial para desenvolvedores que visam desenhar APIs que aderem às melhores práticas, garantindo clareza e eficiência na comunicação entre clientes e servidores. Este guia explorará as diferenças entre URIs baseadas em ações e URIs baseadas em recursos, a importância dos métodos HTTP, códigos de status e fornecerá exemplos práticos para solidificar seu entendimento.
Prós e Contras das URIs Baseadas em Recursos
Prós:

Clareza: Melhora a legibilidade e compreensão ao estruturar URIs em torno de recursos.
Escalabilidade: Facilita a expansão e manutenção das APIs.
Consistência: Promove uniformidade entre diferentes endpoints, tornando a API mais previsível.

Contras:

Complexidade Inicial: Pode exigir uma compreensão mais profunda dos princípios REST.
Rigidez: A adesão estrita pode, às vezes, limitar a flexibilidade em certos cenários.

Visão Geral Comparativa



Característica
URIs Baseadas em Ações
URIs Baseadas em Recursos




Estrutura
Usa verbos indicando ações (ex., /getBrands)
Foca em recursos (ex., /brands)


Legibilidade
Pode ser confuso devido a termos de ação variados
Mais intuitivo e organizado em torno da hierarquia de recursos


Conformidade com REST
Menos alinhado com os princípios RESTful
Totalmente aderente aos padrões RESTful


Escalabilidade
Pode se tornar trabalhoso conforme a API cresce
Facilmente escalável com gestão clara de recursos




Capítulo 1: Compreendendo URIs Baseadas em Recursos
O que são URIs Baseadas em Recursos?
URIs Baseadas em Recursos são endpoints que representam recursos específicos dentro de uma aplicação ou serviço. Em vez de focar em ações ou operações, essas URIs são estruturadas em torno das entidades que representam, como brands, bikes e spares em um contexto de showroom.
Importância das URIs Baseadas em Recursos
Adotar URIs baseadas em recursos alinha o design da sua API com os princípios RESTful, promovendo escalabilidade, manutenibilidade e clareza. Essa abordagem simplifica a interação entre clientes e servidores, fornecendo uma maneira clara e consistente de acessar e manipular recursos.
Quando e Onde Usar URIs Baseadas em Recursos
URIs baseadas em recursos são ideais para:

APIs RESTful: Garantindo adesão aos padrões REST.
Arquitetura de Microserviços: Facilitando o design de serviços modulares e escaláveis.
Qualquer Design de API: Onde clareza e manutenibilidade são prioridades.


Capítulo 2: URIs Baseadas em Ações vs. URIs Baseadas em Recursos
URIs Baseadas em Ações
URIs Baseadas em Ações incorporam verbos para denotar ações ou operações específicas. Por exemplo:

/getBrands
/setBikes
/deleteSpare?id=25

Embora essa abordagem possa funcionar, ela frequentemente leva a confusão e inconsistência, especialmente conforme a API cresce.
URIs Baseadas em Recursos
URIs Baseadas em Recursos focam nas entidades envolvidas:

/brands
/brands/bajaj
/bikes/honda

Essa estrutura melhora a legibilidade e alinha-se com as melhores práticas RESTful.
Análise Comparativa



Aspecto
URIs Baseadas em Ações
URIs Baseadas em Recursos




Uso de Verbos
Inclui verbos de ação (get, set)
Usa substantivos representando recursos


Clareza
Menos intuitivo
Mais intuitivo e organizado


Conformidade com REST
Menos alinhado com os princípios REST
Totalmente aderente aos padrões RESTful


Manutenção
Pode se tornar trabalhoso
Mais fácil de manter e escalar




Capítulo 3: Desenhando URIs Baseadas em Recursos Eficazes
Estruturando suas URIs
URIs baseadas em recursos eficazes seguem uma estrutura hierárquica, representando as relações entre os recursos. Por exemplo:

/brands – Acessando todas as brands.
/brands/bajaj – Acessando uma brand específica, Bajaj.
/bikes/honda – Acessando todas as bikes da brand Honda.
/spares/suzuki – Acessando spares relacionados à Suzuki.
/spares/25 – Acessando uma peça de reposição específica pelo ID.

Melhores Práticas

Use Substantivos no Plural: Representar coleções no plural (ex., /brands).
Representação Hierárquica: Refletir a relação entre os recursos através da estrutura da URI.
Convênios de Nomenclatura Consistentes: Manter uniformidade na nomenclatura das URIs para previsibilidade.

Exemplo Prático
Imagine uma API de showroom onde você pode acessar diferentes brands, suas bikes e peças de reposição. Uma estrutura de URI bem desenhada baseada em recursos pode se parecer com isto:




		
		
			
			
Java
			
			/brands
/brands/bajaj
/bikes
/bikes/honda
/spares
/spares/suzuki
/spares/25
			
				
					
				
					1
2
3
4
5
6
7
				
						/brands
/brands/bajaj
/bikes
/bikes/honda
/spares
/spares/suzuki
/spares/25
					
				
			
		



Capítulo 4: Métodos HTTP em URIs Baseadas em Recursos
Visão Geral dos Métodos HTTP
Métodos HTTP definem as ações que podem ser realizadas nos recursos. Os métodos mais comumente usados em APIs RESTful são:

GET: Recuperar informações.
POST: Criar um novo recurso.
PUT: Atualizar um recurso existente.
DELETE: Remover um recurso.

Explicação Detalhada

GET: Usado para buscar dados de um recurso. Por exemplo, GET /brands recupera todas as brands.
POST: Usado para criar um novo recurso. Por exemplo, POST /brands adiciona uma nova brand.
PUT: Usado para atualizar um recurso existente. Por exemplo, PUT /brands/bajaj atualiza as informações da brand Bajaj.
DELETE: Usado para deletar um recurso. Por exemplo, DELETE /spares/25 remove a peça de reposição com ID 25.

Mapeamento de Métodos para Operações



Método HTTP
Operação
Exemplo de URI




GET
Recuperar recurso(s)
/brands


POST
Criar um novo recurso
/brands


PUT
Atualizar um recurso existente
/brands/bajaj


DELETE
Deletar um recurso
/spares/25




Capítulo 5: Códigos de Status HTTP Explicados
Importância dos Códigos de Status
Os códigos de status HTTP comunicam o resultado da solicitação de um cliente ao servidor. Eles fornecem feedback essencial sobre se a operação foi bem-sucedida ou se ocorreram erros.
Códigos de Status Comuns

200 OK: A solicitação foi bem-sucedida.
201 Created: Um novo recurso foi criado com sucesso.
404 Not Found: O recurso solicitado não existe.
500 Internal Server Error: Ocorreu um erro genérico no servidor.

Categorização dos Códigos de Status



Categoria
Faixa de Código
Descrição




1xx
100-199
Respostas informativas


2xx
200-299
Respostas de sucesso


3xx
300-399
Mensagens de redirecionamento


4xx
400-499
Respostas de erro do cliente


5xx
500-599
Respostas de erro do servidor



Uso Prático
Quando um cliente faz uma solicitação para GET /brands, uma recuperação bem-sucedida retornaria um status 200 OK. Tentar acessar uma peça de reposição inexistente usando GET /spares/999 resultaria em um status 404 Not Found.

Capítulo 6: Implementando URIs Baseadas em Recursos: Um Exemplo Prático
Cenário: API de Showroom
Vamos considerar um showroom que gerencia brands, bikes e peças de reposição. Implementaremos URIs baseadas em recursos para lidar com essas entidades.
Exemplos de URIs
Brands:

GET /brands – Recuperar todas as brands.
GET /brands/bajaj – Recuperar informações sobre a brand Bajaj.
POST /brands – Adicionar uma nova brand.
PUT /brands/bajaj – Atualizar as informações da brand Bajaj.
DELETE /brands/bajaj – Remover a brand Bajaj do sistema.

Bikes:

GET /bikes – Recuperar todas as bikes.
GET /bikes/honda – Recuperar bikes da brand Honda.
POST /bikes – Adicionar uma nova bike.
PUT /bikes/honda – Atualizar as informações das bikes Honda.
DELETE /bikes/honda – Remover as bikes Honda.

Spares:

GET /spares – Recuperar todas as peças de reposição.
GET /spares/suzuki – Recuperar peças de reposição para a Suzuki.
GET /spares/25 – Recuperar a peça de reposição com ID 25.
POST /spares – Adicionar uma nova peça de reposição.
PUT /spares/25 – Atualizar a peça de reposição com ID 25.
DELETE /spares/25 – Remover a peça de reposição com ID 25.

Exemplo de Implementação de Código
Abaixo está um exemplo simples usando Node.js e Express para implementar URIs baseadas em recursos para gerenciar brands.




		
		
			
			
Java
			
			const express = require('express');
const app = express();
app.use(express.json());

let brands = [
  { id: 1, name: 'Bajaj' },
  { id: 2, name: 'Honda' },
];

// Get all brands
app.get('/brands', (req, res) => {
  res.status(200).json(brands);
});

// Get a specific brand
app.get('/brands/:name', (req, res) => {
  const brand = brands.find(b => b.name.toLowerCase() === req.params.name.toLowerCase());
  if (!brand) return res.status(404).send('Brand not found');
  res.status(200).json(brand);
});

// Add a new brand
app.post('/brands', (req, res) => {
  const newBrand = {
    id: brands.length + 1,
    name: req.body.name,
  };
  brands.push(newBrand);
  res.status(201).json(newBrand);
});

// Update a brand
app.put('/brands/:name', (req, res) => {
  const brand = brands.find(b => b.name.toLowerCase() === req.params.name.toLowerCase());
  if (!brand) return res.status(404).send('Brand not found');
  brand.name = req.body.name;
  res.status(200).json(brand);
});

// Delete a brand
app.delete('/brands/:name', (req, res) => {
  const brandIndex = brands.findIndex(b => b.name.toLowerCase() === req.params.name.toLowerCase());
  if (brandIndex === -1) return res.status(404).send('Brand not found');
  const deletedBrand = brands.splice(brandIndex, 1);
  res.status(200).json(deletedBrand);
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Server running on port ${PORT}`));
			
				
					
				
					1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
				
						const express = require('express');
const app = express();
app.use(express.json());
 
let brands = [
  { id: 1, name: 'Bajaj' },
  { id: 2, name: 'Honda' },
];
 
// Get all brands
app.get('/brands', (req, res) => {
  res.status(200).json(brands);
});
 
// Get a specific brand
app.get('/brands/:name', (req, res) => {
  const brand = brands.find(b => b.name.toLowerCase() === req.params.name.toLowerCase());
  if (!brand) return res.status(404).send('Brand not found');
  res.status(200).json(brand);
});
 
// Add a new brand
app.post('/brands', (req, res) => {
  const newBrand = {
    id: brands.length + 1,
    name: req.body.name,
  };
  brands.push(newBrand);
  res.status(201).json(newBrand);
});
 
// Update a brand
app.put('/brands/:name', (req, res) => {
  const brand = brands.find(b => b.name.toLowerCase() === req.params.name.toLowerCase());
  if (!brand) return res.status(404).send('Brand not found');
  brand.name = req.body.name;
  res.status(200).json(brand);
});
 
// Delete a brand
app.delete('/brands/:name', (req, res) => {
  const brandIndex = brands.findIndex(b => b.name.toLowerCase() === req.params.name.toLowerCase());
  if (brandIndex === -1) return res.status(404).send('Brand not found');
  const deletedBrand = brands.splice(brandIndex, 1);
  res.status(200).json(deletedBrand);
});
 
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Server running on port ${PORT}`));
					
				
			
		


Explicação do Código

Configuração: Inicializamos uma aplicação Express e definimos um array de brands de exemplo.
GET /brands: Recupera a lista de todas as brands, respondendo com um status 200 OK.
GET /brands/:name: Busca uma brand específica pelo nome. Se não encontrada, retorna um 404 Not Found.
POST /brands: Adiciona uma nova brand à coleção, respondendo com um status 201 Created.
PUT /brands/:name: Atualiza o nome de uma brand existente. Se a brand não existir, retorna um 404 Not Found.
DELETE /brands/:name: Remove uma brand da coleção. Se a brand não for encontrada, retorna um 404 Not Found.

Exemplo de Saída
Requisição: GET /brands
Resposta:




		
		
			
			
Java
			
			[
  { "id": 1, "name": "Bajaj" },
  { "id": 2, "name": "Honda" }
]
			
				
					
				
					1
2
3
4
				
						[
  { "id": 1, "name": "Bajaj" },
  { "id": 2, "name": "Honda" }
]
					
				
			
		



Capítulo 7: Melhores Práticas e Convenções
Nomenclatura Consistente
Use substantivos no plural para nomes de recursos para representar coleções. Por exemplo, use /brands em vez de /brand.
Estrutura Hierárquica
Refletir a relação entre os recursos através da estrutura da URI. Recursos aninhados devem representar sua hierarquia de forma lógica.
Uso de Métodos HTTP
Utilize os métodos HTTP apropriados para realizar operações nos recursos, garantindo adesão aos princípios RESTful.
Versionamento
Implemente versionamento nas suas URIs para gerenciar mudanças ao longo do tempo sem interromper os clientes existentes. Por exemplo:




		
		
			
			
Java
			
			/v1/brands
/v2/brands
			
				
					
				
					1
2
				
						/v1/brands
/v2/brands
					
				
			
		


Tratamento de Erros
Forneça mensagens de erro significativas e códigos de status HTTP apropriados para ajudar os clientes a entender o resultado de suas solicitações.
Documentação
Mantenha uma documentação abrangente da sua API, detalhando endpoints disponíveis, métodos, parâmetros e respostas esperadas.

Conclusão
URIs baseadas em recursos são a pedra angular do design de APIs RESTful, oferecendo uma abordagem estruturada e intuitiva para gerenciar recursos. Ao focar nas entidades em vez das ações, desenvolvedores podem criar APIs que são escaláveis, de fácil manutenção e facilmente compreendidas pelos clientes.
Adotar melhores práticas no design de URIs, uso apropriado dos métodos HTTP e tratamento eficaz de erros garante que suas APIs não apenas atendam aos requisitos atuais, mas também sejam adaptáveis às necessidades futuras. Quer você esteja construindo uma aplicação simples ou uma arquitetura complexa de microserviços, as URIs baseadas em recursos fornecem a base para um desenvolvimento de API robusto e eficiente.
Nota: Este artigo foi gerado por IA.
Método HTTP	Operação	Exemplo de URI
GET	Recuperar recurso(s)	/brands
POST	Criar um novo recurso	/brands
PUT	Atualizar um recurso existente	/brands/bajaj
DELETE	Deletar um recurso	/spares/25
Característica	URIs Baseadas em Ações	URIs Baseadas em Recursos
Estrutura	Usa verbos indicando ações (ex., /getBrands)	Foca em recursos (ex., /brands)
Legibilidade	Pode ser confuso devido a termos de ação variados	Mais intuitivo e organizado em torno da hierarquia de recursos
Conformidade com REST	Menos alinhado com os princípios RESTful	Totalmente aderente aos padrões RESTful
Escalabilidade	Pode se tornar trabalhoso conforme a API cresce	Facilmente escalável com gestão clara de recursos
Aspecto	URIs Baseadas em Ações	URIs Baseadas em Recursos
Uso de Verbos	Inclui verbos de ação (get, set)	Usa substantivos representando recursos
Clareza	Menos intuitivo	Mais intuitivo e organizado
Conformidade com REST	Menos alinhado com os princípios REST	Totalmente aderente aos padrões RESTful
Manutenção	Pode se tornar trabalhoso	Mais fácil de manter e escalar
Categoria	Faixa de Código	Descrição
1xx	100-199	Respostas informativas
2xx	200-299	Respostas de sucesso
3xx	300-399	Mensagens de redirecionamento
4xx	400-499	Respostas de erro do cliente
5xx	500-599	Respostas de erro do servidor