Guia para implementar uma API REST.

design-api.md

O que é uma API ?

• API é um conjunto de funções provida por um software. Uma API web pode ser acessada através de um request HTTP e é esperado uma resposta HTTP geralmente no formato XML ou JSON, o padrão de API's web é SOAP ou REST sendo essa ultima a mais utilizada.

Design REST API

Termologias

• Resource é um objeto ou uma representação de alguma coisa que tem associação com algum dado. Ex: Animal, Escola e Empresa são resources e delete, add, update e search são operações a serem realizadas em cima dos resources.
• Collections são conjuntos de resources. Ex: Empresas é uma collections de recursos chamado Empresa.
• URL é o caminho pelo qual um recurso pode ser localizado. A url deve conter apenas o nome do resource no plural sem ações ou verbos. Exemplo incorreto: /addNovaEmpresa. Exemplo correto: /empresas.

Métodos HTTP

Use os métodos HTTP para indicar qual ação a API irá realizar em cima do resource.

HTTP Method	Quando usar
GET	Consultas e operações de somente leitura
PUT	Atualizar um recurso de maneira idempotente
POST	Criar um recurso ou atualizar não idempotente, ou outras operações
DELETE	Remove um recurso de uma maneira idempotente
PATCH(não usado com frequência)	Atualizar parcialmente um recurso

Exemplos de API

Método: GET Path: /empresas Descrição: Pesquisa empresas, retorna a lista de todas as empresas.

Método: GET Path: /empresas/5 Descrição: Busca a empresa que tenha o id 5.

Método: GET Path: /empresas?categoria=financeira Descrição: Pesquisa uma lista de todas as empresas aplicando um filtro de categoria financeira.

Método: GET Path: /empresas?search=Apple Descrição: Consulta empresas que tenham o nome Apple.

Método: GET Path: /empresas?page=18 Descrição: Quando você vai consultar um lista muito grande de resources, nós dividimos conjuntos de dados em partes menores, o que ajuda a melhorar o desempenho da resposta. Faz uma paginação das 18 primeiras empresas.

Método: GET Path: /empresas?sort=Nome Descrição: Pesquisa empresas, retorna a lista de todas as empresas ordenada pelo campo nome.

Método: POST Path: /empresas Descrição: Cria um novo resource de empresa. Body:

{
	"nome": "Apple",
	"endereço": "Avenida Paulista",
	"CNPJ": 14245434535345
}

Método: PUT Path: /empresas Descrição: Atualiza um resource existente de modo idempotente. Body:

{
	"id": 1,
	"nome": "Coca",
	"endereço": "Avenida Paulista",
	"CNPJ": 14245434535345
}

Método: DELETE Path: /empresas Descrição: Deleta um resource existente. Body:

{
	"id": 1,
	"nome": "Coca",
	"endereço": "Avenida Paulista",
	"CNPJ": 14245434535345
}

HTTP status codes

Sempre quando construir uma API deve-se retornar um código indicando o que ocorreu, para isso deve-se usar HTTP status codes, segue a baixo os principais:

HTTP status	Description
200	Success
201	Recurso criado com sucesso
202	Iniciado uma tarefa assincronamente com sucesso
400	Erro na validação de dados ou erro de processamento da requisição
401	Credenciais de usuário invalida fornecidas para autenticação
403	Acesso negado
409	A requisição criou um conflito (duplicate key)
415	O content-type no header da requisição é um tipo não suportado
500	Erro inesperado no processamento da requisição

2xx - Sucesso. 4xx - Quando o cliente errar de alguma forma. 5xx - Erro inesperado no servidor.

HATEOAS