O paradigma REST A transferência de Estado Representacional (REST) é a escolha mais popular para o desenvolvimento da API nos últimos anos. Baseado no conceito central de recursos. Um recurso é uma entidade que pode ser identificada, nomeada, endereçada ou tratada na web. As APIs REST expõem dados como recursos e usam métodos HTTP padrão para representar transações Criar, Ler, Atualizar e Excluir (CRUD) contra esses recursos. Requisição HTTP para recuperar uma cobrança da API Stripe **GET** /v1/charges/ch_CWyut1Xs9pZyfD HOST api.stripe.com Authorization: Bearer YNoJlYq64iCBhzfL9HNO00fzVrsEjtV Requisição HTTP para enviar uma cobrança na API Stripe POST /v1/charges HOST api.stripe.com Content-Type: application/x-www-form-urlencoded Authorization: Bea rer YNoJlYq64iCBhzfL9HNO00fzVrsEjtVl amount=2000&currency=usd Métodos HTTP como GET, POST, UPDATE e DELETE informam o servidor sobre a ação a ser realizada. Diferentes métodos HTTP invocados na mesma URL fornecem funcionalidades diferentes. Criar: Use o POST, na maioria dos casos, para criar novos recursos. Ler: Use o GET para ler recursos. Requisições GET nunca mudam o estado do recurso. Elas não têm efeitos colaterais. O GET é idempotente. Atualização: Use o PUT para substituir um recurso e PATCH para atualizações parciais para os recursos existentes. o PUT também é idempotente Excluir: Use o DELETE para excluir recursos existentes. O DELETE também é idempotente Os recursos fazem parte de URLs, como /usuarios Para cada recurso, duas URLs são geralmente implementadas: uma para a coleção, como /usuarios, e uma para elemento específico, como /usuarios/U123 Nomes são usados em vez de verbos para definir recursos. Por exemplo, em vez de /lerInformacaoUsuario/U123, use /usuario/U123. Imagine que você envia uma carta para alguém. A resposta que você recebe de volta pode ser: ✅ "Entregue com sucesso!" 🔄 "O destinatário se mudou, tente outro endereço" ❌ "Carta com endereço errado" 💥 "O correio teve um problema interno" É exatamente assim que funcionam os códigos HTTP — são respostas do servidor ao seu navegador/aplicação. Geralmente, os códigos na faixa 2XX indicam sucesso, 3XX indicam que um recurso de moveu e códigos na faixa 4XX indicam um erro do lado do cliente (como um parâmetro necessário ausente ou muitas solicitações). Códigos na faixa 5XX indicam erros do lado do servidor. O servidor recebeu, entendeu e processou sua requisição. Código Nome Significado 200 OK Tudo certo! Resposta padrão de sucesso 201 Created Um recurso foi criado (ex: cadastro feito) 204 No Content Sucesso, mas sem nada para retornar O recurso que você pediu está em outro lugar. Código Nome Significado 301 Moved Permanently Mudou de endereço para sempre 302 Found Redirecionamento temporário 304 Not Modified Use o cache, nada mudou Você fez algo errado na requisição. Código Nome Significado 400 Bad Request Requisição mal formada 401 Unauthorized Precisa estar autenticado (fazer login) 403 Forbidden Autenticado, mas sem permissão 404 Not Found O recurso não existe 429 Too Many Requests Você fez requisições demais (rate limit) O servidor que teve um problema, não você. Código Nome Significado 500 Internal Server Error Erro genérico no servidor 502 Bad Gateway Servidor intermediário recebeu resposta inválida 503 Service Unavailable Servidor fora do ar ou sobrecarregado 504 Gateway Timeout O servidor demorou demais para responder As APIs REST podem devolver respostas JSON ou XML. E devido à sua simplicidade e facilidade de uso com Javascript, o JSON tornou-se o padrão para APIs modernas. O XML e outros formatos ainda podem ser suportados para facilitar a adoção para clientes que ainda estão trabalhando nesse formatos usando APIs semelhantes. No Brasil, o XML é comum em APIs do governo para facilitar a governança dos dados, como NF-E ou E-Social Operação Verbo HTTP URL: /usuarios URL: /usuários/123 Criar POST Cria um novo usuário Não é aplicável Ler GET Lista todos os usuários Recupera o usuário 123 Atualizar PUT ou PATCH Atualiza em lote os usuários Atualiza o usuário 123 Remover DELETE Apaga todos os usuários Apaga o usuário 123 Verbo HTTP URI Exemplo Semântica POST /livros/123/autores Criar os autores para o livro 123 GET /livros/123/autores/1 Recupera o autor 1 do livro 123 PUT ou PATCH /livros/123/autores/1 Atualiza os dados do autor 1 do livro 123 DELETE /livros/123/autores Apaga todos os autores do livro 123 Além das operações típicas da CRUD que acabamos de olhar, as APIs REST às vezes precisam representar operações não-CRUD. As seguintes abordagens são comumente usadas nesse caso: Crie uma ação como um subrecurso. GET livros/empromocao Crie uma ação através de parâmetros de entrada GET livros?tipo=empromocao&categoria=autoajuda