Histórico da Página
...
Verbo | Usado para | Tipo de operação | Código de sucesso | Detalhes | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
POST | Criar uma entidade | Síncrona | 201 | Além do código de sucesso deve retornar a nova entidade criada. | ||||||||||
PATCH ou PUT | Atualizar uma entidade | Síncrona | 200 | Além do código de sucesso deve retornar a nova entidade atualizada. | ||||||||||
POST, PUT | Criar ou atualizar entidade | Assíncrona | 202 | O código 202 informa ao cliente que o serviço aceitou a requisição para processamento e que isso pode levar um tempo para concluir. Nesse caso o endpoint deve retornar o campo Location no cabeçalho da resposta apontando para onde a nova entidade poderá ser encontradaum recurso temporário que permita o acompanhamento do status da requisição. Por exemplo, considere o endpoint de cadastro assíncrono de usuários:
DEVE retornar como resposta:
|
Como escolher o método adequado
...
Informações | ||
---|---|---|
| ||
Os campos do JSON que representam data devem usar o formato definido no documento ISO-8601 no formato EXTENDIDO. |
Mensagens de erro
Âncora | ||||
---|---|---|---|---|
|
Para todas as mensagens que representam um erro (códigos HTTP 4xx e 5xx) deve-se retornar obrigatoriamente os campos a seguir:
...
Caso a regra de negócio necessitar de um retorno com conteúdo, este deve vir com HTTP Code 200 (OK) e com a entidade excluída sem expandir os sub-níveis.
Âncora | ||||
---|---|---|---|---|
|
Dividimos os erros em duas categorias: Erros de negócio ou requisição e Erros não esperados.
...
Informações | ||
---|---|---|
| ||
A API deve suportar a expansão de até dois níveis de propriedade de retorno, ex: prop1.prop2.prop3. Nos casos em que o objeto tenha uma sub coleção o numero máximo de registros dessa coleção não deve ultrapassar 20 registros. Se houver a necessidade de retornar mais itens deve-se considerar criar um endpoint especifico para retornar a coleção com suporte a filtro, ordenação, etc. |
Requisições Assíncronas.
Ao realizar um POST, PUT ou DELETE em um recurso que executa seu processamento de maneira assíncrona, o mesmo DEVE retornar o código 202 Accepted, com cabeçalho location apontando para um recurso temporário que permita o acompanhamento do status da requisição.
Processando
Ao realizar o GET no recurso temporário, enquanto ainda estiver sendo processado, o mesmo DEVE retornar o código 200 e um JSON com a propriedade status definida como “pending”. Esse retorno PODE, e é uma boa prática, retornar a propriedade progress, informando o percentual de conclusão da operação solicitada.
Outra propriedade que PODE constar nesse retorno é a canCancel. Quandodefinida como “true”, significa que cancelar aquele processamento é permitido para o client. Quando inexistente, ou definida como “false”, o cancelamento não está permitido.
Bloco de código | ||||
---|---|---|---|---|
| ||||
{
“status”: “pending”,
“progress”: “30%”,
“canCancel”: true
} |
Para cancelar a execução do processamento, quando permitido, o client deve executar DELETE no recurso temporário.
Finalizada – Erro
Ao acessar o recurso temporário que finalizou seu processamento com erros, retorna o erro adequado, conforme definido em Mensagens de Erro e Código 4xx versus 5xx
Finalizada – Sucesso
Ao acessar o recurso temporário que finalizou seu processamento com sucesso, o mesmo DEVE retornar o código 303 (See Other) com o cabeçalho Location, apontando para endereço do real recurso criado.
A deleção do recurso temporário não é obrigatória e PODE ser feita através de DELETE do client, ou através do próprio server, após um tempo determinado para expirá-lo. Nesse segundo caso, ao tentar acessá-lo DEVE retornar 410 (Gone).
Versionamento
...