...

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:

...

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

• O campo helpUrl deve apontar diretamente para documentação do erro na API;

• identificar unicamente o erro 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 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);

• 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:

{
  contentdata: {}
}

Âncora
ApiSuccessMsgColl ApiSuccessMsgColl

Mensagens de sucesso para coleções

...

{
  contentdata: {
    hasNext: true,
    items: [
      {},
      {},
      ...
    ]
  }
}

...