REST em Profundidade

Convenções REST. Versionamento de API. Paginação por cursor vs offset. Resposta padronizada. Modelo de maturidade Richardson.

RESTversionamentopaginaçãocursorHATEOASconvenções

REST em profundidade

Boas APIs REST seguem convenções que tornam a interface previsível para qualquer desenvolvedor. Recursos, verbos semânticos, respostas padronizadas e paginação consistente.

📐

HATEOAS

A constraint mais ignorada: respostas incluem links para ações relacionadas. Nível de maturidade 3 do modelo Richardson. Poucos usam, mas é o REST 'completo'.

Versionamento de API

APIs mudam. Versionar permite evoluir sem quebrar clientes existentes.

URL path

/api/v1/users — mais explícito, mais usado

Header

Accept: application/vnd.api+json;version=2

Query string

/users?version=2 — menos recomendado

Paginação e filtros

Nunca retorne todos os registros de uma vez. Implemente paginação por offset ou cursor.

🔖

cursor vs offset

Offset: página 2 = OFFSET 20. Problema: se novos itens foram inseridos, você vê duplicatas. Cursor: depois de id=450. Estável mesmo com inserções. Use cursor para feeds e listas dinâmicas.

javascript
// API REST bem estruturada — resposta padronizada
const apiResponse = (data, meta = {}) => ({
  data,
  meta: { timestamp: new Date().toISOString(), ...meta }
})

// Paginação com cursor
app.get('/api/v1/products', async (req, res) => {
  const { limit = 20, after, category, sort = 'createdAt' } = req.query

  const products = await db.query(`
    SELECT * FROM products
    WHERE ($1::text IS NULL OR id > $1)
      AND ($2::text IS NULL OR category = $2)
    ORDER BY ${sort} DESC LIMIT $3
  `, [after, category, Number(limit) + 1])

  const hasNext = products.length > limit
  if (hasNext) products.pop()

  res.json(apiResponse(products, {
    cursor: hasNext ? products.at(-1)?.id : null,
    hasNext
  }))
})

⚡

quiz · aula 35

Teste seus conhecimentos

0/3 respondidas

QUESTÃO 01

Qual é a vantagem de paginação por cursor sobre offset?

QUESTÃO 02

Por que versionar uma API com /api/v1/ na URL?

QUESTÃO 03

Qual é o modelo de maturidade Richardson?

0/3

← aula anterior

O que é uma API

aula 35 de 67

módulo 4

próxima aula →

JSON: o Formato de Dados