Histórico da Página
...
Squad | Membro |
---|---|
SDK | Marcelo De Aguiar |
Identity / Portal | Paulo Roberto Francisco Junior |
LMS | Diego Lopes |
BPM | Gustavo Martins De Souza |
PAAS / Fundação | Vanei Anderson Heidemann |
ECM | Andre Felipe Joriatti |
Integração | Danilo Pacheco Martins |
Estrutura de URLs
Como regra geral seguimos os passos abaixo sempre que precisarmos criar um novo recurso:
- Determinar o tipo de recurso que está sendo exposto pelo endpoint;
- Determinar o relacionamento do recurso que está sendo criado e os recursos já existentes;
- Decidir o caminho e o nome do recurso com base no seu tipo e o seu relacionamento com os outros recursos;
- Anexar os métodos mínimos para o correto funcionamento do endpoint.
Os caminhos definidos para cada endpoint devem ser de fácil leitura e significativos para o cliente para facilitar a sua descoberta e adoção. Os pontos abaixo devem ser Os caminhos definidos para cada endpoint devem ser de fácil leitura e significativos para o cliente para facilitar a sua descoberta e adoção. Os pontos abaixo devem ser considerados ao criar uma URL:
...
Bloco de código | ||
---|---|---|
| ||
{ code: "Código identificador do erro", helpUrl: "link para a documentação do error", message: "Literal no idioma da requisição descrevendo o erro para o cliente", detailedMessage: "Mensagem técnica e mais detalhada do erro" } |
- O campo code deve identificar unicamente o erro na documentação da API;
Informações |
---|
Todos os códigos de error devem estar mapeados e listados na documentação da API. |
- O campo helpUrl deve apontar diretamente para documentação do erro na API;
- identificar unicamente o erro na documentação da API;
Informações |
---|
Todos os códigos de error devem estar mapeados e listados na documentação da API. |
- O campo helpUrl deve apontar diretamente para documentação do erro na API;
- O campo message deve descrever o erro de forma não técnica e pode ser usado pelos clientes para exibição ao usuário. O texto deste campo deve respeitar o idioma usado na requisição (definido pelo cabeçalho Accept-Language ou o padrão caso este não seja especificado). Além disso leve em consideração:
- Não assuma que o usuário é um especialista no uso da sua API. Usuário podem incluir desenvolvedores, profissionais de TI, administradores e usuários finais;
- Não assuma que o usuário saiba qualquer coisa sobre a implementação da função sendo exposta pelo endpoint;
- Quando possível a mensagem deve ser construida de forma que um usuário técnico possa responder ao erro e corrigi-lo;
- Mantenha a mensagem sucinta e, se necessário, inclua um link para a documentação de como corrigi-la.
- O campo detailedMessage deve descrever o erro de forma mais técnica e pode conter referências que ajudem na correção / localização do erro no contexto do servidor do fluig.
...
Mensagens de sucesso devem ser retornadas para todos os códigos http 2xx e devem ter pelo menos o campo content campo data que representa o objeto resultado da operação do endpoint. Ex:
Bloco de código | ||
---|---|---|
| ||
{ contentdata: {} } |
Âncora | ||||
---|---|---|---|---|
|
...
Bloco de código | ||
---|---|---|
| ||
{ contentdata: { hasNext: true, items: [ {}, {}, ... ] } } |
...