nomeando recursos no REST

Nomeando recursos no REST

Compartilhe nas redes sociais

No REST, a representação de dados primários é chamada de recurso. Ter uma estratégia de nomenclatura de recursos REST forte e consistente provará uma das melhores decisões de design em longo prazo.

A principal abstração de informações no REST é um recurso. Qualquer informação que possa ser nomeada pode ser um recurso: um documento ou imagem, um serviço temporal (por exemplo, “clima de hoje em Los Angeles”), uma coleção de outros recursos, um objeto não virtual (por exemplo, uma pessoa), e assim por diante. Em outras palavras, qualquer conceito que possa ser alvo de referência de hipertexto de um autor deve se enquadrar na definição de um recurso. Um recurso é um mapeamento conceitual para um conjunto de entidades, não a entidade que corresponde ao mapeamento em um determinado momento. — Dissertação de Roy Fielding

Um recurso pode ser um singleton ou uma coleção. Por exemplo, “customers” é um recurso de coleção e “customer” é um recurso único (em um domínio bancário). Podemos identificar o recurso de coleção “customers” usando o URI “/customers”. Podemos identificar um recurso singleton “customer” usando o URI “/customers/{customer-id}”.

Um recurso pode conter outros recursos de coleção também. Por exemplo, um sub-recurso de coleção “accounts” de um “customer” em particular pode ser identificado usando a URN “/customers/{customer-id}/accounts” (em um domínio bancário). De maneira similar, um recurso único dentro de um recurso de coleção “accounts” pode ser identificado como a seguir: “/customers/{customerId}/accounts/{account-id}”.

APIs REST usam Uniform Resource Identifiers (URIs) para endereçar recursos. Os responsáveis por “desenhar” a API REST devem criar URIs que transmitam um modelo de recursos da API REST para seus desenvolvedores clientes em potencial. Quando os recursos são nomeados corretamente, uma API é intuitiva e fácil de usar. Se feito de maneira inadequada, a mesma API pode parecer difícil de usar e entender.

A restrição de uma interface uniforme é parcialmente tratada pela combinação de URIs e verbos HTTP, usando-os de acordo com os padrões e convenções.

Abaixo estão algumas dicas para você começar a criar os URIs de recursos para sua nova API.

Práticas recomendadas de nomeação de recursos REST

Use substantivos para representar recursos

O URI RESTful deve referir-se a um recurso que é uma coisa (substantivo) em vez de se referir a uma ação (verbo) porque os substantivos têm propriedades que os verbos não possuem – semelhantes aos recursos que têm atributos. Alguns exemplos de um recurso são:

  • Usuários de um sistema
  • Contas de um usuário
  • Dispositivos de rede, etc.

e seus URIs de recursos podem ser projetados conforme abaixo:

http://api.example.com/device-management/managed-devices 
http://api.example.com/device-management/managed-devices/{device-id}
http://api.example.com/user-management/users/
http://api.example.com/user-management/users/{user-id}

Para mais clareza, vamos dividir os arquétipos de recursos em quatro categorias (documento, coleção, armazenamento e controlador), em seguida, você deve sempre colocar um recurso em um arquétipo e, então, usar sua convenção de nomenclatura de forma consistente. Para o bem da uniformidade, resista à tentação de projetar recursos que sejam híbridos de mais de um arquétipo.

  1. Documento: Um recurso de documento é um conceito singular que se assemelha a uma instância de objeto ou registro de banco de dados. No REST, você pode visualizá-lo como um único recurso dentro da coleção de recursos. A representação do estado de um documento normalmente inclui campos com valores e links para outros recursos relacionados.Use o nome no “singular” para denotar o arquétipo do recurso do documento.
    http://api.example.com/device-management/managed-devices/{device-id} 
    http://api.example.com/user-management/users/{user-id}
    http://api.example.com/user-management/users/admin
  2. Coleção: Um recurso de coleção é um diretório de recursos gerenciado pelo servidor. Os clientes podem propor novos recursos a serem adicionados a uma coleção. Porém, cabe à coleção optar por criar um novo recurso ou não. Um recurso de coleção escolhe o que deseja conter e também decide os URIs de cada recurso contido.Use o nome no “plural” para denotar o arquétipo do recurso de coleção.
    http://api.example.com/device-management/managed-devices 
    http://api.example.com/user-management/users
    http://api.example.com/user-management/users/{user-id}/accounts
  3. Armazenamento: Uma recurso de armazenamento é um repositório de recursos gerenciado pelo cliente. Ele permite que um consumidor da API (client) coloque recursos, recupere-os e decida quando excluí-los. Um recurso de armazenamento nunca gera novos URIs. Em vez disso, cada recurso armazenado possui um URI. O URI foi escolhido por um client quando foi inicialmente colocado na loja.Use o nome no “plural” para denotar o arquétipo do recurso de armazenamento.
    http://api.example.com/song-management/users/{user-id}/playlists
  4. Controlador: Um recurso controlador modela um conceito de procedimento. Os recursos controladores são como funções executáveis, com parâmetros e valores de retorno; entradas e saídas.Use um “verbo” para denotar o arquétipo do recurso controlador.
    http://api.example.com/cart-management/users/{user-id}/cart/checkout
    http://api.example.com/song-management/users/{user-id}/playlist/play

Consistência é a chave

Use convenções de nomenclatura de recursos consistentes e formatação de URI para obter o mínimo de ambiguidade e o máximo de legibilidade e manutenção. Você pode implementar as dicas de design abaixo para obter consistência:

  1. Use barra (/) para indicar relações hierárquicas: O caractere de barra (/) é usado na parte do caminho do URI para indicar um relacionamento hierárquico entre os recursos. por exemplo:
    http://api.example.com/device-management 
    http://api.example.com/device-management/managed-devices
    http://api.example.com/device-management/managed-devices/{device-id}
    http://api.example.com/device-management/managed-devices/{device-id}/scripts
    http://api.example.com/device-management/managed-devices/{device-id}/scripts/{script-id}
  2. Não use barra final (/) em URIsComo último caractere em um caminho de URI, uma barra (/) não adiciona nenhum valor semântico e pode causar confusão. É melhor abandoná-los completamente.
    http://api.example.com/device-management/managed-devices/ 
    http://api.example.com/device-management/managed-devices  /* Versão muito melhor */
  3. Use hífens (-) para melhorar a legibilidade dos URIs: Para tornar seus URIs fáceis de serem verificados e interpretados pelas pessoas, use o caractere hífen (-) para melhorar a legibilidade dos nomes em segmentos de caminho longo.
    http://api.example.com/inventory-management/managed-entities/{id}/install-script-location  // Mais legível 
    http://api.example.com/inventory-management/managedEntities/{id}/installScriptLocation  // Menos legível
  4. Não use underscores, underline, sublinhado ( _ ): É possível usar um underscore no lugar de um hífen para ser usado como separador – Mas dependendo da fonte do aplicativo, é possível que o caractere de underscore ( _ ) possa ficar parcialmente obscurecido ou completamente oculto em alguns navegadores ou telas.Para evitar essa confusão, use hifens ( – ) em vez de underscores ( _ ).
    http://api.example.com/inventory-management/managed-entities/{id}/install-script-location  // Mais legível 
    http://api.example.com/inventory_management/managed_entities/{id}/install_script_location  // Mais sujeito a erros
  5. Use letras minúsculas em URIs: Quando conveniente, letras minúsculas devem ser consistentemente preferidas em caminhos de URI.RFC 3986 define URIs com distinção entre maiúsculas e minúsculas, exceto para o esquema e os componentes do host. por exemplo:
    http://api.example.org/my-folder/my-doc  //1 
    HTTP://API.EXAMPLE.ORG/my-folder/my-doc  //2
    http://api.example.org/My-Folder/my-doc  //3

    Nos exemplos acima, 1 e 2 são iguais, mas 3 não é, porque usa “My-Folder” em letras maiúsculas.

  6. Não use extensões de arquivo: As extensões de arquivo têm uma aparência ruim e não acrescentam nenhuma vantagem. Removê-los também diminui o comprimento dos URIs. Não há razão para mantê-los.Além do motivo acima, se você deseja destacar o tipo de mídia da API usando extensão de arquivo, é melhor você confiar no tipo de mídia (media type), informado por meio do cabeçalho Content-Type, para determinar como processar o conteúdo do corpo da requisição.
    http://api.example.com/device-management/managed-devices.xml  /* Não use isso */ 
    http://api.example.com/device-management/managed-devices  /* Este é o URI correto */

Nunca use nomes de função CRUD em URIs

URIs não devem ser usados para indicar que uma função CRUD é executada. URIs devem ser usados para identificar recursos de forma exclusiva e não qualquer ação sobre eles. Os métodos de solicitação HTTP devem ser usados para indicar qual função CRUD é executada.

HTTP GET http://api.example.com/device-management/managed-devices // Obter todos os dispositivos 
HTTP POST http://api.example.com/device-management/managed-devices // Criar novo dispositivo 
HTTP GET http://api.example.com/device-management/managed-devices/{id} // Obter dispositivo para determinado ID 
HTTP PUT http://api.example.com/device-management/managed-devices/{id} // Atualizar dispositivo para determinado ID 
HTTP DELETE http://api.example.com/device-management/managed-devices/{id} // Excluir dispositivo para determinado ID

Use query strings para filtrar em uma URI de coleção

Muitas vezes, você encontrará requisitos em que precisará de uma coleção de recursos classificados, filtrados ou limitados com base em algum atributo de recurso específico. Para isso, não crie novas APIs – em vez disso, habilite os recursos de classificação, filtragem e paginação na API de coleta de recursos e passe os parâmetros de entrada como parâmetros de consulta. Por exemplo:

http://api.example.com/device-management/managed-devices 
http://api.example.com/device-management/managed-devices?region=USA
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date