...

PRECISAMOS FAZER UMA POC TESTANDO VARIOS JARS E UM WAR PADRE

• /me
• /por card?
  

Coleções

Ordenação

Ordenação usando parametro order precedido de + para crescente (padrao) e - decrescente

Filtros

Marcelo - pesquisar schin|skin|scan|etc filter. mas tem que ser via get provavel que com q param;

 Paulo - Vai procurar um framework que faça o parse dessa string.

Paginação

...

Todos os endpoints de coleção DEVEM suportar ordenação. A definição de como a lista deve ser ordenada é definida no parâmetro de url order respeitando as seguintes regras:

• O parâmetro da url DEVE ter o nome order;
• O valor do parâmetro order é uma lista de campos, separada por virgula (,) opcionalmente precedida pelos sinal de adição (+) ou subtração (-);
  
• A lista DEVE respeitar a ordem dos campos como descrito na url para fazer a ordenação;
• Campos precedidos por um sinal de subtração (-) devem ser ordenados de forma decrescente;
• Campos precedidos por um sinal de adição (+) devem ser ordenados de forma crescente;
• Campos que omitirem o sinal (de adição ou subtração) devem ser ordenados de forma crescente.

Por exemplo, a seguinte requisição deve retornar a lista de usuários ordenados pelo nome de forma crescente e então pela idade de forma decrescente e então pelo sobrenome de forma crescente:

GET https://fluig.totvs.com.br/api/users?order=name,-age,+surname

Filtros

Marcelo - pesquisar schin|skin|scan|etc filter. mas tem que ser via get provavel que com q param;

 Paulo - Vai procurar um framework que faça o parse dessa string.

Paginação

Todos os endpoints de coleção DEVEM suportar paginação. A definição de como a coleção deve ser paginada é definida pelos parâmetros de url page e pageSize respeitando as seguintes regras:

• Os parâmetros da url DEVEM ter os nomes page e pageSize;
• O valor do parâmetro page DEVE ser um valor numérico maior que zero representando a página solicitada;
• O parâmetro page é OPCIONAL e na sua ausência deve ser considerado o valor 1;
  
• O valor do parâmetro pageSize DEVE ser um valor numérico maior que zero representando o total de registros retornados na consulta;
• O parâmetro pageSize é OPCIONAL e na sua ausência deve ser considerado o valor 20;
• Os parâmetros de paginação DEVEM obedecer a semântica de multiplicador, ou seja, se o cliente solicitou page=2 com um pageSize=20 deve-se retornar os registros de 21 até 40;
• A resposta de uma requisição com paginação DEVE retornar um campo indicando se existe uma próxima página disponível conforme descrito na mensagem de sucesso de lista (linkar) e esse campo DEVE ter o nome hasNext.

Por exemplo, a seguinte requisição deve retornar a terceira página de registros (dos registros 31 á 40 INCLUSIVE) de usuários:

GET https://fluig.totvs.com.br/api/users?page=4&pageSize=10

Métodos suportados

Endpoints devem usar os métodos HTTP adequados e devem respeitar a idempotência da operação.

...

POST http://fluig.totvs.com/api/users/10

{
  name: "",
  age: 20,
  ...
}

POST http://fluig.totvs.com/api/users/10

{
  name: "Novo nome do usuário"
}

POST x PUT x PATCH

Deve-se atentar aos códigos de retorno para os tipos de operações definidos para usar estes métodos principalmente nos casos definidos abaixo:

...

Formato das mensagens de resposta

Só JASÃO

JSON DEVE ser o formato padrão para mensagens e as propriedades destas mensagens DEVEM ser escritas usando camelCase.

...

Erros de negócio ou requisição são aqueles causados por dados inválidos na requisiçõe ou intencionalmente lançados do endpoint para o cliente. Todos os erros deste tipo devem obrigatoriamente retornar um código HTTP 4xx. Ex:. Ex:

1. O cliente chamou um endpoint mas não estava devidamente autenticado. Deve ser retornado o código 401 - Unauthorized
2. O cliente chamou um endpoint mas mesmo estando autenticado não possui as permissões necessárias para efetuar a operação. Deve retornar o código 403 - Forbidden
3. O cliente chamou o endpoint para buscar um usuário (Ex: /users/{id}) mas o usuário não existeO cliente chamou um endpoint mas não estava devidamente autenticado. Deve ser retornado o código 401 - Unauthorizedde erro 404 - Not found
4. O cliente chamou um endpoint mas mesmo estando autenticado não possui as permissões necessárias para efetuar a operação. Deve retornar o código 403 - Forbiddeno endpoint para efetuar alguma operação mas por alguma regra de negócio a operação não pode ser concluída e não existe um código de erro HTTP apropriado para descrevê-lo. Deve ser retornado o código de error 400 - Bad Request
5. O cliente chamou o endpoint para buscar um usuário (Ex: /users/{id}) mas o usuário não existe. Deve ser retornado o código de erro 404 - Not found
6. O cliente chamou o endpoint para efetuar alguma operação mas por alguma regra de negócio a operação não pode ser concluída e não existe um código de erro HTTP apropriado para descrevê-lo. Deve ser retornado o código de error 400 - Bad Request
7. passando no cabeçalho que aceita como retorno xml (Content-Type: text/xml) mas o serviço consegue retornar JSON. Deve retornar o erro HTTP 406 - Not Acceptable
8. O cliente chamou um endpoint para subir um documento mas o usuário logado passou o limite de espaço estipulado para seu perfil. Deve retornar o código 507 - Insufficiente Storage;

Erros não esperados são os erros não tratados ou não intencionais. Esse tipo de erro devesempre retornar códigos HTTP 5xx. Ex:

1. O cliente chamou um endpoint mas o servidor não pode responder por que estava sobrecarregado. Deve retornar o código 503 - Service Unavailable;O cliente chamou o endpoint passando no cabeçalho que aceita como retorno xml (Content-Type: text/xml) mas o serviço consegue retornar JSON. Deve retornar o erro HTTP 406 - Not Acceptable
2. O cliente chamou um endpoint para subir um documento mas o usuário logado passou o limite de espaço estipulado para seu perfilnão havia espaço em disco no servidor. Deve retornar o código 507 - Insufficiente Storage;

...

Mensagens de sucesso

Mensagens de sucesso DEVEM ser retornadas para todos os códigos http 2xx e DEVEM ter pelo menos o campo content que representa o objeto resultado da operação do endpoint. Ex:

{
  content: {}
}

Mensagens de sucesso para coleções

Nos casos em que o resultado da operação do endpoint represente uma coleção além do campo content deve ser retornado o campo hasNext indicando se existe uma próxima página com mais registros para aquela coleção

1. O cliente chamou um endpoint mas o servidor não pode responder por que estava sobrecarregado. Deve retornar o código 503 - Service Unavailable;
2. O cliente chamou um endpoint para subir um documento mas não havia espaço em disco no servidor. Deve retornar o código 507 - Insufficiente Storage;

Mensagens de sucesso

Validar o generics com a documentação do swagger.

{
   ...hasNext: true,
  hasNextcontent: se[
 for lista
  {},
   content: {},
    ...
  ]
}

...

Parâmetros expansíveis

Todos os endpoints DEVEM respeitar e suportar os campos expansíveis. E DEVEM retornar os campos retraídos a menos que especificado na requisição atráves do parâmetro de url expand.

...