Histórico da Página
...
- Definir práticas e padrões consistentes para todos os endpoints das APIs da TOTVS;
- Garantir a utilização mais próxima possível das boas práticas estipuladas pelos padrões REST/HTTP;
- Tornar os serviços da TOTVS acessíveis através de APIs facilmente compreendidas e documentadas para desenvolvedores e consumidores.
Nota | ||
---|---|---|
| ||
prop1.prop2.prop3.Atente-se para esta documentação. Para garantir um bom desenvolvimento de APIs publicas ou privadas, é imprescindível que os passos a seguir sejam respeitados. |
...
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 é recomendável que o numero número máximo de registros dessa coleção não deve ultrapassar ultrapasse 20 registros. Se houver a necessidade de retornar 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
...