Design de APIs REST

import http from "node:http";
import { randomUUID } from "node:crypto";

type Item = { produtoId: string; quantidade: number };
type Pedido = { id: string; clienteId: string; itens: Item[]; status: string; criadoEm: string };

const pedidos = new Map<string, Pedido>();
const ERROS = "https://api.loja.com.br/erros";

function problema(res: http.ServerResponse, status: number, tipo: string, titulo: string, extra = {}) {
  res.writeHead(status, { "Content-Type": "application/problem+json" });
  res.end(JSON.stringify({ type: `${ERROS}/${tipo}`, title: titulo, status, ...extra }));
}

function validar(corpo: any): Record<string, string> {
  const erros: Record<string, string> = {};
  if (typeof corpo?.clienteId !== "string" || !corpo.clienteId) erros.clienteId = "obrigatório";
  if (!Array.isArray(corpo?.itens) || corpo.itens.length === 0) erros.itens = "precisa de pelo menos um item";
  corpo?.itens?.forEach?.((item: any, i: number) => {
    if (!Number.isInteger(item?.quantidade) || item.quantidade < 1) erros[`itens[${i}].quantidade`] = "inteiro maior que zero";
  });
  return erros;
}

http.createServer(async (req, res) => {
  if (req.method !== "POST" || req.url !== "/pedidos") {
    return problema(res, 404, "nao-encontrado", "Recurso não encontrado");
  }

  let corpo: any;
  try {
    let texto = "";
    for await (const parte of req) texto += parte;
    corpo = JSON.parse(texto);
  } catch {
    return problema(res, 400, "json-invalido", "O corpo não é um JSON válido");
  }

  const erros = validar(corpo);
  if (Object.keys(erros).length > 0) {
    return problema(res, 422, "dados-invalidos", "Os dados enviados são inválidos", { errors: erros });
  }

  const pedido: Pedido = {
    id: randomUUID(),
    clienteId: corpo.clienteId,
    itens: corpo.itens,
    status: "aberto",
    criadoEm: new Date().toISOString(),
  };
  pedidos.set(pedido.id, pedido);

  res.writeHead(201, { "Content-Type": "application/json", Location: `/pedidos/${pedido.id}` });
  res.end(JSON.stringify(pedido));
}).listen(3000);

from datetime import datetime, timezone
from uuid import uuid4

from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from pydantic import BaseModel, ConfigDict, Field
from pydantic.alias_generators import to_camel

ERROS = "https://api.loja.com.br/erros"
app = FastAPI()
pedidos: dict[str, dict] = {}


class Modelo(BaseModel):
    # Campos em snake_case no Python, camelCase no JSON
    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)


class Item(Modelo):
    produto_id: str
    quantidade: int = Field(gt=0)


class NovoPedido(Modelo):
    cliente_id: str = Field(min_length=1)
    itens: list[Item] = Field(min_length=1)


def problema(status: int, tipo: str, titulo: str, **extra) -> JSONResponse:
    return JSONResponse(
        status_code=status,
        media_type="application/problem+json",
        content={"type": f"{ERROS}/{tipo}", "title": titulo, "status": status, **extra},
    )


# Troca o formato de erro padrão do FastAPI pelo Problem Details
@app.exception_handler(RequestValidationError)
async def dados_invalidos(request: Request, exc: RequestValidationError):
    if any(erro["type"] == "json_invalid" for erro in exc.errors()):
        return problema(400, "json-invalido", "O corpo não é um JSON válido")
    erros = {".".join(str(p) for p in erro["loc"][1:]): erro["msg"] for erro in exc.errors()}
    return problema(422, "dados-invalidos", "Os dados enviados são inválidos", errors=erros)


@app.post("/pedidos", status_code=201)
def criar_pedido(novo: NovoPedido):
    pedido = {
        "id": str(uuid4()),
        "clienteId": novo.cliente_id,
        "itens": [item.model_dump(by_alias=True) for item in novo.itens],
        "status": "aberto",
        "criadoEm": datetime.now(timezone.utc).isoformat(),
    }
    pedidos[pedido["id"]] = pedido
    return JSONResponse(status_code=201, content=pedido, headers={"Location": f"/pedidos/{pedido['id']}"})

package main

import (
	"crypto/rand"
	"encoding/json"
	"fmt"
	"net/http"
	"sync"
	"time"
)

const erros = "https://api.loja.com.br/erros"

type Item struct {
	ProdutoID  string `json:"produtoId"`
	Quantidade int    `json:"quantidade"`
}

type Pedido struct {
	ID        string `json:"id"`
	ClienteID string `json:"clienteId"`
	Itens     []Item `json:"itens"`
	Status    string `json:"status"`
	CriadoEm  string `json:"criadoEm"`
}

var (
	mu      sync.Mutex
	pedidos = map[string]Pedido{}
)

func problema(w http.ResponseWriter, status int, tipo, titulo string, extra map[string]any) {
	corpo := map[string]any{"type": erros + "/" + tipo, "title": titulo, "status": status}
	for k, v := range extra {
		corpo[k] = v
	}
	w.Header().Set("Content-Type", "application/problem+json")
	w.WriteHeader(status)
	json.NewEncoder(w).Encode(corpo)
}

func criarPedido(w http.ResponseWriter, r *http.Request) {
	var novo Pedido
	if err := json.NewDecoder(r.Body).Decode(&novo); err != nil {
		problema(w, 400, "json-invalido", "O corpo não é um JSON válido", nil)
		return
	}

	invalidos := map[string]string{}
	if novo.ClienteID == "" {
		invalidos["clienteId"] = "obrigatório"
	}
	if len(novo.Itens) == 0 {
		invalidos["itens"] = "precisa de pelo menos um item"
	}
	for i, item := range novo.Itens {
		if item.Quantidade < 1 {
			invalidos[fmt.Sprintf("itens[%d].quantidade", i)] = "inteiro maior que zero"
		}
	}
	if len(invalidos) > 0 {
		problema(w, 422, "dados-invalidos", "Os dados enviados são inválidos", map[string]any{"errors": invalidos})
		return
	}

	pedido := Pedido{ID: rand.Text(), ClienteID: novo.ClienteID, Itens: novo.Itens,
		Status: "aberto", CriadoEm: time.Now().UTC().Format(time.RFC3339)}
	mu.Lock()
	pedidos[pedido.ID] = pedido
	mu.Unlock()

	w.Header().Set("Content-Type", "application/json")
	w.Header().Set("Location", "/pedidos/"+pedido.ID)
	w.WriteHeader(http.StatusCreated)
	json.NewEncoder(w).Encode(pedido)
}

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("POST /pedidos", criarPedido)
	http.ListenAndServe(":3000", mux)
}

import jakarta.validation.Valid;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotEmpty;
import jakarta.validation.constraints.Positive;
import java.net.URI;
import java.time.Instant;
import java.util.List;
import java.util.Map;
import java.util.UUID;
import java.util.concurrent.ConcurrentHashMap;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

// Com spring.mvc.problemdetails.enabled=true, o Spring Boot 3 devolve
// erros de validação e de JSON malformado como application/problem+json
@RestController
public class PedidosController {
    record Item(@NotBlank String produtoId, @Positive int quantidade) {}
    record NovoPedido(@NotBlank String clienteId, @NotEmpty List<@Valid Item> itens) {}
    record Pedido(String id, String clienteId, List<Item> itens, String status, Instant criadoEm) {}

    private final Map<String, Pedido> pedidos = new ConcurrentHashMap<>();

    @PostMapping("/pedidos")
    public ResponseEntity<Pedido> criar(@Valid @RequestBody NovoPedido novo) {
        var pedido = new Pedido(UUID.randomUUID().toString(), novo.clienteId(),
            novo.itens(), "aberto", Instant.now());
        pedidos.put(pedido.id(), pedido);
        return ResponseEntity.created(URI.create("/pedidos/" + pedido.id())).body(pedido);
    }
}

using System.Collections.Concurrent;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails(); // erros como application/problem+json

var app = builder.Build();
app.UseStatusCodePages();
var pedidos = new ConcurrentDictionary<string, Pedido>();

app.MapPost("/pedidos", (NovoPedido novo) =>
{
    var erros = new Dictionary<string, string[]>();
    if (string.IsNullOrWhiteSpace(novo.ClienteId))
        erros["clienteId"] = ["obrigatório"];
    if (novo.Itens is not { Count: > 0 })
        erros["itens"] = ["precisa de pelo menos um item"];
    for (var i = 0; i < (novo.Itens?.Count ?? 0); i++)
        if (novo.Itens![i].Quantidade < 1)
            erros[$"itens[{i}].quantidade"] = ["inteiro maior que zero"];

    if (erros.Count > 0)
        return Results.ValidationProblem(erros, statusCode: 422, title: "Os dados enviados são inválidos");

    var pedido = new Pedido(Guid.NewGuid().ToString(), novo.ClienteId!, novo.Itens!,
        "aberto", DateTime.UtcNow);
    pedidos[pedido.Id] = pedido;
    return Results.Created($"/pedidos/{pedido.Id}", pedido);
});

app.Run();

record Item(string ProdutoId, int Quantidade);
record NovoPedido(string? ClienteId, List<Item>? Itens);
record Pedido(string Id, string ClienteId, List<Item> Itens, string Status, DateTime CriadoEm);