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.

{
        "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

Padrão HATEOAS.

Esse estilo de arquitetura permite usar links no conteúdo da resposta para que o cliente possa navegar dinamicamente para o recurso apropriado. Isso é conceitualmente o mesmo que um usuário da Web navegando pelas páginas e clicando nos hiperlinks apropriados para atingir uma meta final.

O padrão HATEOAS deve ser utilizado no retorno de entidades relacionadas a principal e que não são parte do recurso princiapal. Ex.

GET https

http://totvs.com/api/fluig/fdn/v1/users
http://totvs.com/api/fluig/fdn/v1.5/users
http://totvs.com/api/fluig/fdn/v2/users

Duas versões da API podem ser suportadas e neste caso deve existir uma politica de depreciação e esta deve estar documentada em um local acessível ao usuário final.

Quando alterar a versão?

O numero da versão indica para o cliente quando alguma alteração pode "quebrar" o código escrito por ele. Deve-se tomar um cuidado especial no processo de versionamento para que o cliente esteja ciente dessas alterações e a frequência com que elas acontecem usando algum tipo de release notes ou documentação.

Alterações que devem gerar uma nova versão "major":

• URIs foram removidas ou renomeadas;
• Foram removidos campos do retorno de um endpoint;
• Foi removido o suporte a um método do endpoint (GET, PUT, POST, etc);
• Um novo parâmetro obrigatório é exigido para o correto funcionamento do endpoint;
• Um novo endpoint foi adicionado a API.

Alterações que NÃO devem gerar uma nova versão "major":

• Um novo formato de retorno é suportado pelo endpoint;
• Novas propriedades são retornadas na entidade de retorno do endpoint;
• Novos parâmetros opcionais podem ser passados para o endpoint.

Documentação

/10
{
        "id" : 10,
        "name" : "Usuário",
        "age" : 25,
		 "links": [
        { "rel": "communities",  "href": "/fdn/v1/communities/5" },
        { "rel": "permissions",  "href": "/fdn/v1/permissions/30" }
          ]             
}

http://totvs.com/api/fluig/fdn/v1/users
http://totvs.com/api/fluig/fdn/v1.5/users
http://totvs.com/api/fluig/fdn/v2/users

Duas versões da API podem ser suportadas e neste caso deve existir uma politica de depreciação e esta deve estar documentada em um local acessível ao usuário final.

Quando alterar a versão?

O numero da versão indica para o cliente quando alguma alteração pode "quebrar" o código escrito por ele. Deve-se tomar um cuidado especial no processo de versionamento para que o cliente esteja ciente dessas alterações e a frequência com que elas acontecem usando algum tipo de release notes ou documentação.

Alterações que devem gerar uma nova versão "major":

• URIs foram removidas ou renomeadas;
• Foram removidos campos do retorno de um endpoint;
• Foi removido o suporte a um método do endpoint (GET, PUT, POST, etc);
• Um novo parâmetro obrigatório é exigido para o correto funcionamento do endpoint;
• Um novo endpoint foi adicionado a API.

Alterações que NÃO devem gerar uma nova versão "major":

• Um novo formato de retorno é suportado pelo endpoint;
• Novas propriedades são retornadas na entidade de retorno do endpoint;
• Novos parâmetros opcionais podem ser passados para o endpoint.

Documentação

Todas os métodos, parâmetros, códigos de erro e mensagens de requisição e retorno da API publica devem estar documentadas na página de documentação. Além disso deve ser gerado um documento OpenAPI com as definições da API.