Histórico da Página
...
Informações |
---|
Mais informações sobre a escolha do valor máximo de caracteres pode ser consultada em: https://blogs.msdn.microsoft.com/ieinternals/2014/08/13/url-length-limits/ |
Agrupamento
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
Parametros page e pageSize e deve retornar um hasNext indicando se existe uma nova página.
Métodos suportados
Endpoints devem usar os métodos HTTP adequados e devem respeitar a idempotência da operação.
...
Método | Descrição | Idempotente | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
GET | Retorna o valor corrente do objeto. | Sim | ||||||||||
PUT | Sobrescreve o objeto quando aplicável. Por exemplo: O cliente gostaria de sobrescrever o usuário com novos valores:
| Sim | ||||||||||
DELETE | Exclui o objeto. | Sim | ||||||||||
POST | Cria um novo objeto ou submete um comando ao objeto. | Não | ||||||||||
HEAD | Retorna os metadados da requisição em casos em que o cliente não precisa do corpo das requisições do tipo GET. | Sim | ||||||||||
PATCH | PATH foi padronizado pelo IETF como o método usado para atualizar um objeto de forma incremental (ver RFC 5789), ou seja, apenas as propriedades informadas pelo cliente serão atualizadas. Por exemplo: O cliente gostaria de atualizar o nome do usuário e para isso vai usar o endpoint de atualização de usuários
O servidor deverá implementar o serviço de modo que apenas o nome do usuário seja atualizado e todas as outras propriedades mantidas. | Não | ||||||||||
OPTIONS | nao vai ter | OPTIONS | Retorna informações sobre um endpoint e sobre as operações suportadas por ele; ver abaixo para mais detalhes. | Sim |
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
Precisamos decidir se vamos suportar XML E Json ou apenas um deles.Só JASÃO
JSON DEVE ser o formato padrão para mensagens e as propriedades destas mensagens DEVEM ser escritas usando camelCase.
...
- 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 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
Mensagens de sucesso
Validar o generics com a documentação do swagger.
Bloco de código | ||
---|---|---|
| ||
{
...
hasNext: se for lista
content: {} | ||
Bloco de código | ||
| ||
{
} |
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.
...
- Todas as propriedades que representam listas ou objetos DEVEM vir retraídas por padrão e DEVEM usar a notação de lista vazia (Ex.: [] ).
- Todas as propriedades que representam objetos DEVEM vir retraídos e usar a notação de objeto sem propriedades. (Ex.: {} )
...
Por exemplo, a entidade usuário possui propriedades que apontam para suas permissões, comunidades e detalhes e portanto estas dem devem estar retraídas:
Bloco de código | ||
---|---|---|
| ||
POSTGET https://fluig.totvs.com/api/users/10 { _expandables: ["permissions", "communities", "detailedInformation"], id: 10, name: "Usuário", age: 25, permissions: [], communities: [], detailedInformation: {}, ... } |
...
Bloco de código | ||
---|---|---|
| ||
POSTGET https://fluig.totvs.com/api/users/10?expand=communities { _expandables: ["permissions", "detailedInformation"], id: 10, name: "Usuário", age: 25, permissions: [], communities: [{ _expandables: [permissions], name: "Vendas", photoUrl: "https://fluig.totvs.com/communities/1/photo", permissions: {} }, { _expandables: [permissions], name: "Outra comunidade", photoUrl: "https://fluig.totvs.com/communities/2/photo", permissions: {} }], detailedInformation: {}, ... } |
...
Bloco de código | ||
---|---|---|
| ||
POSTGET https://fluig.totvs.com/api/users/10?expand=communities.permissions { _expandables: ["permissions", "detailedInformation"], id: 10, name: "Usuário", age: 25, permissions: [], communities: [{ name: "Vendas", photoUrl: "https://fluig.totvs.com/communities/1/photo", permissions: { isAdmin: true, canView: true } }, { name: "Outra comunidade", photoUrl: "https://fluig.totvs.com/communities/2/photo", permissions: { isAdmin: true, canView: true } }], detailedInformation: {}, ... } |
Versionamento
- API interna deve seguir esse padrão, mas é independe do versionamento. Deve estar documentado (tecnica) para as novas.
- Validar como passar a versão URL ou header. Testar com o Paulo.
Dicas de como implementar os métodos para tentar manter um padrão de implementação.
Documentação
- Tem que sair com swagger (json e documentação)