REST vs RESTful API

RESTful vs REST

REST significa REpresentational State Transfer (transferência de estado representacional), que consiste em princípios que permitem a criação de um projeto com interfaces bem definidas. Ao adotar uma arquitetura que traz como base essa organização e definição de sua estrutura, todo o seu consumo e implementação acontecem de uma forma mais natural.

RESTful é um padrão de arquitetura de software para criar e disponibilizar serviços na web, as famosas APIs. A padronização RESTful permite ao desenvolvedor elaborar de forma mais fácil suas aplicações e APIs, visto que, a partir da adesão ao RESTful, já temos a garantia de como serão desenvolvidas e consumidas as APIs.

Existe uma certa confusão entre os termos REST e RESTful, mas eles representam os mesmos princípios e a diferença entre eles é apenas gramatical, em outras palavras, sistemas que utilizam os princípios REST são chamados de RESTful. O REST é o conjunto de princípios arquiteturais, já o Restful é a capacidade de um determinado sistema aplicar os princípios do Rest.

E as APIs? Estas são um conjunto de rotinas e padrões estabelecidos e documentados por uma aplicação A, para que outras aplicações consigam utilizar funcionalidades desta aplicação A, sem precisar conhecer detalhes da implementação do software. Desta forma, entendemos que as APIs permitem uma interoperabilidade entre aplicações. Em outras palavras, a comunicação entre aplicações e entre os usuários.

A origem
O HTTP é o principal protocolo de comunicação para sistemas Web e existe há mais de 20 anos. Nos anos 2000, um dos principais autores do protocolo HTTP, Roy Fielding, sugeriu, dentre outras coisas, o uso de novos métodos HTTP, métodos estes que se propunham a resolver problemas relacionados à semântica quando requisições HTTP eram feitas.

Estas sugestões permitiram o uso do HTTP de uma forma mais próxima da nossa realidade, dando sentido às requisições HTTP conforme:

GET http://www.meusite.com/usuarios
DELETE http://www.meusite.com/usuarios/dailton
POST http://www.meusite.com/usuarios -data {nome: tadashi}

É possível inferir que no primeiro caso estamos pegando (GET) todos os usuários do site, ou seja, teremos uma lista de todos os usuários que estão cadastrados. Já, no segundo caso, estamos apagando (DELETE) o usuário Dailton. No último exemplo, estamos usando o método POST, em que percebemos o envio de dados extras para cadastrar um novo usuário.

Endpoints
Como mostrado acima, seu serviço irá prover uma URL base e os verbos HTTP vão indicar qual ação está sendo requisitada pelo consumidor do serviço. Mas quais seriam esses verbos? Abaixo, os principais:

Verbo GET: é usado para ler ou recuperar uma representação de um recurso.
Verbo POST: é mais frequentemente utilizado para criar novos recursos.
Verbo DELETE: é usado para excluir um recurso identificado por um URI.
Verbo PUT: é mais utilizado para substituir (ou atualizar) recursos, executando
a requisição para uma URI de recurso conhecido, com o corpo da requisição contendo a representação recém-atualizada do recurso original.
Verbo PATCH: é usado para modificar parcialmente os recursos. A requisição só precisa conter as alterações específicas para o recurso, não o recurso completo.
Algumas dicas para padrão de nomenclatura.

Dê preferência para o plural ao disponibilizar o resource. Utilize /users ao invés de /user.
Se um recurso possui um nome composto utilize o "kebab-case". Por exemplo Global Configuration seria GET /global-configuration.
Dê preferência para URLs em minúsculo, evite GET /Users, use GET /users.

Ações
Algumas vezes os endpoints não traduzem a complexidade do negócio. Nestes casos, especificar ações para os endpoints se fazem necessários. Convém reforçar que o uso de ações não fere o uso do padrão REST.

Um exemplo da utilização de uma ação em um endpoint seria:

http://www.meusite.com/usuarios/{1}/status

Documentação
O Open API é hoje o padrão mais utilizado para documentar APIs.

Sua implementação é relativamente simples em várias linguagens de programação. Além de documentar, ele disponibiliza também mecanismos para testar sua API no Browser.

Respostas
Quando o servidor recebe uma solicitação HTTP, o cliente deve saber o resultado da ação. Se houve sucesso ou falhou. Os códigos de status HTTP são vários códigos padronizados, com várias explicações em vários cenários. O servidor sempre deve retornar o código de status correto.

A seguir estão as categorias dos códigos HTTP:

2xx - Status de sucesso
3xx - Categoria de redirecionamento
4xx - Erro no Cliente
5xx - Erro no server

Resumo

RESTful que é um padrão de arquitetura de software para criar e disponibilizar serviços na web. Listamos os seus principais verbos, como se criar uma ação, documentação e suas mensagem de retorno por categoria.

Referência
[RESTful Web APIs: Services for a Changing World - Leonard Richardson, Mike Amundsen]