Guia Pocket para construção de API's
O servidor retorna um código indicando o resultado do seu processamento, conhecido como HTTP Status.
O status da família 2XX indica sucesso da operação solicitada, tendo como principais códigos ao lado:
200
ok.
201 - created (criado)
Quando determinado, foi criado corretamente.
202 - accepted (aceito)
Comumente utilizado em transações assíncronas, indicando que a comunicação foi bem-sucedida, mas ainda não foi processada.
O status da família 4XX indica que alguma informação passada pelo usuário está incorreta ou que alguma validação da regra impediu o processo. Os status mais comuns são:
400 - Bad Request
Alguma informação não corresponde ao esperado, geralmente atrelado à regra de negócio.
401 - unauthorized & 403 forbidden
O usuário passado não tem acesso ao sistema ou não tem permissão para executar a ação desejada, respectivamente.
404 - Not found
O recurso solicitado não foi encontrado.
Utilizado quando ocorre algum erro inesperado no servidor e que, não necessariamente, está ligado às informações da requisição do usuário. Os status mais usados são:
500 - Internal server error
Erro inesperado ou não tratado no servidor.
502 - Bad gateway
API Gateway não conseguiu se comunicar com o backend.
503 - Service unavailable
o servidor está em manutenção ou indisponível temporariamente.
Na API, utilizamos semantic versioning, um padrão que é dividido em major, minor e patch. Somente a Major Version é utilizada na URL. Por exemplo:
Mudança de Minor Version:
1.001 
1.002
1.002 URL continua V1
Mudança de Major Version:
1.001 2.000
2.000 URL DEVE ser alterada para V2
Header: Requisições HTTP são divididas em header e body. Alguns parâmetros são enviados no header, como Authorization.
Path: É possível definir um parâmetro junto com a URL. Geralmente, ele é utilizado para identificar a entidade a ser requisitada ou processada. No padrão da TOTVS, esses IDs DEVEM estar presentes no corpo da requisição.
Ao processar uma requisição, o servidor irá gerar uma resposta que, além do HTTP Status, pode apresentar um conteúdo (corpo):
Sucesso
Ao processar um item, a API pode ou não retornar um corpo na resposta, Dependendo da ação realizada. O padrão é definido pela área que cria a API
Lista
Uma resposta a uma lista no padrão TOTVS deve conter 2 atributos. O HasNext indica se há mais algum recurso na base fora da paginação e o Items, a resposta da requisição.
{
“hasNext”: true,
“items”:[{
“nome”: “prod1”,
“id” : 1
},{
“nome”: “prod2”,
"id”: 2
}]
}
“hasNext”: true,
“items”:[{
“nome”: “prod1”,
“id” : 1
},{
“nome”: “prod2”,
"id”: 2
}]
}
Erro
Mensagens de erro na API TOTVS são padronizadas com o propósito de facilitar a interpretação do erro gerado durante o processamento da requisição. A estrutura permite o uso da propriedade Detail, que é uma lista de erros:
{
“code”: “fw01”,
“message” : “invalid property”,
“details":[
{...}
]
}
“code”: “fw01”,
“message” : “invalid property”,
“details":[
{...}
]
}