Tenho uma pergunta relacionada ao design de url REST. Encontrei alguns posts relevantes aqui: Diferentes representações RESTful do mesmo recurso e aqui: RESTful url para GET recurso por campos diferentes, mas as respostas não são muito claras sobre quais são as melhores práticas e por quê. Aqui está um exemplo.
Eu tenho urls REST para representar o recurso "usuários". Posso OBTER um usuário com um id ou com um endereço de e-mail, mas a representação do URL permanece a mesma para ambos. Ao ler muitos blogs e livros, vejo que as pessoas têm feito isso de muitas maneiras diferentes. Por exemplo
leia essa prática em um livro e em algum lugar no stackoverflow (não consigo encontrar o link novamente)
GET /users/id={id}
GET /users/email={email}
leia esta prática em muitos blogs
GET /users/{id}
GET /users/email/{email}
Os parâmetros de consulta são normalmente usados para filtrar os resultados dos recursos representados pelo url, mas também vi essa prática sendo usada
GET /users?id={id}
GET /users?email={email}
Minha pergunta é, de todas essas práticas, qual faria mais sentido para os desenvolvedores que consomem as apis e por quê? Acredito que não existam regras imutáveis quando se trata de designs de url REST e convenções de nomenclatura, mas eu só queria saber qual caminho devo seguir para ajudar os desenvolvedores a entender melhor as apis.
Todos ajudam apreciados!
fonte
Respostas:
Na minha experiência,
GET /users/{id} GET /users/email/{email}
é a abordagem mais comum. Eu também esperaria que os métodos retornassem um 404 Not Found se um usuário não existir com o fornecidoid
ouemail
. Eu também não ficaria surpreso em verGET /users/id/{id}
(embora, em minha opinião, seja redundante).Comentários sobre as outras abordagens
GET /users/id={id} GET /users/email={email}
GET /users?id={id} GET /users?email={email}
id
e umemail
(por exemploGET /users?id={id}&email={email}
)? Se não, eu não usaria um método de recurso único como este.id
,email
ou qualquer identificador exclusivo, estar entre os parâmetros. Por exemplo:GET /users?status=BANNED
pode retornar uma lista de usuários banidos.Confira esta resposta de uma pergunta relacionada.
fonte
/users/id/{id}
, isso permite funcionalidade estendida, simplesmente permite acessar um recurso através de vários identificadores (id, guid, nome). também respondeu aquiGET /user/1234
e nãoGET /users/123
Olhando para isso de forma pragmática, você tem uma coleção de usuários:
Cada usuário tem um local de recurso dedicado:
Você também tem várias maneiras de pesquisar usuários:
Como todos esses são parâmetros de consulta para / usuários, todos eles devem retornar listas ... mesmo que seja uma lista de 1.
Escrevi uma postagem no blog sobre design pragmático de API RESTful aqui que fala sobre isso, entre outras coisas, aqui: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
fonte
Sobre os recursos do usuário
no caminho,
/users
você sempre obterá uma coleção de recursos do usuário retornados.no caminho,
/users/[user_id]
você pode esperar que várias coisas aconteçam:Cada singleton é identificado exclusivamente por seu caminho e identificador e você os usa para encontrar o recurso. Não é possível usar vários caminhos para o singleton.
Você pode consultar o caminho
/users
com parâmetros de consulta (GET
Parâmetros). Isso retornará uma coleção com usuários que atendem aos critérios solicitados. A coleção que é retornada deve conter os recursos do usuário, todos com seu caminho de recurso de identificação na resposta.Os parâmetros podem ser qualquer campo presente nos recursos da coleção;
firstName
,lastName
,id
Sobre o email
O email pode ser um recurso ou uma propriedade / campo do recurso do usuário.
- E-mail como propriedade do usuário:
Se o campo for uma propriedade do usuário, a resposta do usuário seria algo assim:
Isto significa que há nenhum ponto de extremidade especial para e-mails, mas agora você pode encontrar um usuário pelo seu e-mail, enviando seguinte pedido:
/[email protected]
. Que (assumindo que os emails são exclusivos para usuários) retornaria uma coleção com um item de usuário que corresponde ao email.- Email como recurso:
Mas se e-mails de usuários também são recursos. Então você pode fazer uma API onde
/users/[user_id]/emails
retorna uma coleção de endereços de e-mail para o usuário com iduser_id
./users/[user_id]/emails/[email_id]
retorna o e-mail do usuário com user_id e ['email_id']. O que você usa como um identificador é com você, mas eu ficaria com um número inteiro. Você pode excluir um e-mail do usuário enviando umaDELETE
solicitação para o caminho que identifica o e-mail que você deseja excluir. Assim, por exemplo,DELETE
em/users/[user_id]/emails/[email_id]
apagará o e-mail com email_id que pertence ao usuário com user_id. Provavelmente, apenas esse usuário tem permissão para executar esta operação de exclusão. Outros usuários obterão uma resposta 401.Se um usuário pode ter apenas um endereço de e-mail, você pode ficar com
/users/[user_id]/email
Isso retorna um recurso singleton. O usuário pode atualizar seu endereço de e-mailPUT
digitando o endereço de e-mail naquele url.fonte