Skip to main content

Boas práticas RFC7807

  • Boas práticas RFC7807

Nomenclaturas​

  • Todos os recursos devem ser expressos como substantivo e não como verbo. A prática de evitar verbos nos nomes das rotas é baseada em princípios de design de APIs RESTful, que sugerem que os URLs devem ser usados para identificar recursos, e não ações.
  • Logo ações se fazem necessários no dia-a-dia. E é importante reforçar que não fere os padrões REST.
POST /candidato/{id}/candidatar -- Grava a aplicação de um candidato a uma vaga
POST /candidato/{id}/aprovar -- Aprova um candidato
DELETE /candidato/{id}/aprovar -- Cancela a aprovação
POST /candidato/{id}/reprovar -- Reprova o candidato
DELETE /candidato/{id}/reprovar -- Cancela a reprovação
POST /candidato/{id}/transferir -- Transfere o candidato para outra vaga
DELETE /candidato/{id}/transferir -- Cancela a transferência
  • Deve sempre estar no plural
  • Como expressar relação definida?
    • get /tickets/12/comments
    • Quando a URI for muito extensão, não a obrigação de seguir essa forma

Métodos e seus status code de sucesso​

  • GET - sucesso (200)
  • POST - sucesso (201)
    • Resposta
      • Retornar a representação dos dados criados
      • Adicionar um Location no cabeçalho onde o recurso foi criado
        • Local: http://{server_host}/api/employees/123
  • PUT - sucesso (200)
  • PATCH - sucesso (200)
  • DELETE - sucesso (204)
  • OPTIONS - sucesso (200)
  • HEAD - sucesso (200)

Use nomes descritivos e claros​

  • Escolha nomes que transmitam claramente o propósito e a funcionalidade do endpoint.
  • Evite termos ambíguos ou genéricos. Seja específico e preciso.

Siga as convenções RESTful:​

  • Siga os princípios RESTful sempre que possível. Isso inclui o uso de substantivos para representar recursos e métodos HTTP (GET, POST, PUT, DELETE) para representar ações.

  • Por exemplo, use substantivos como /users/users/{id}

    para representar uma coleção de usuários e

    para um usuário específico.

Use substantivos plurais para coleções:​

  • Use substantivos no plural para terminais que representam coleções de recursos (por exemplo, /users/posts).
  • Use substantivos singulares para pontos finais que representam recursos individuais (por exemplo, /user/{id}/post/{id}).

Estrutura de URL consistente:​

  • Mantenha uma estrutura de URL consistente em sua API para facilitar aos desenvolvedores a previsão de padrões de endpoint.
  • Para recursos aninhados, use uma hierarquia lógica (por exemplo, /users/{userId}/posts/{postId}).

Evite verbos em caminhos de endpoint:​

  • Use métodos HTTP (GET, POST, PUT, DELETE) para indicar ações e manter o caminho do endpoint focado no recurso.
  • Por exemplo, /create prefira /createUser ou /addUser

Versionamento:​

  • Inclua o controle de versão em sua API para garantir a compatibilidade com versões anteriores à medida que sua API evolui.

  • Por exemplo, use /v1/users

    para a versão 1 do endpoint de usuários.

Use hífens ou sublinhados:​

  • Escolha um separador consistente para nomes de recursos com várias palavras. As escolhas comuns são hífens ( /user-profiles ) ou sublinhados (/user_profiles).
  • Atenha-se ao separador escolhido em toda a API para obter consistência.

Forneça filtros e parâmetros de consulta para filtragem:​

  • Permita que os usuários filtrem, classifiquem e paginam os resultados usando parâmetros de consulta em vez de criar endpoints separados para cada variação.
  • Por exemplo, use /users?role=admin/admin-usersem vez de criar um endpoint separado.

Use caracteres minúsculos​

Exceto pelo esquema e pelos componentes de host da URL, os URIs geralmente diferenciam maiúsculas de minúsculas. Isso torna muito importante usar o caso certo ao nomear os recursos. A regra geral é sempre usar caracteres minúsculos porque -

  • É uma convenção amplamente aceita na indústria e ajuda a manter a consistência entre diferentes APIs.
  • As letras minúsculas são geralmente mais fáceis de ler do que as letras maiúsculas, especialmente quando em nomes longos ou URLs.
  • Letras minúsculas são mais comuns em URLs e são usadas pelos mecanismos de pesquisa para indexar páginas da web. Portanto, ao usar letras minúsculas em seus endpoints, você pode ajudar a melhorar a descoberta da API nos mecanismos de pesquisa.

Considere hierarquias de endpoint para relacionamentos:​

  • Represente relacionamentos entre recursos por meio de estruturas hierárquicas em seus endpoints.
  • Por exemplo, /organizations/{orgId}/userspara recuperar usuários de uma organização específica.

Documente sua API:​

  • Forneça documentação abrangente que explique cada endpoint, a entrada esperada e a saída.
  • Inclua exemplos e cenários de uso para ajudar os desenvolvedores a entender como usar sua API de maneira eficaz.