When an authenticated user wishes to access a resource which he exclusively owns, it seems redundant to specify the user id in the URL path.

Thus, in the following examples, which is the more appropriate way to name my API endpoint?

Example 1 User wants to change profile pic

PUT /users/{id}/profile-pic or PUT /profile/profile-pic

Example 2 User wants to add a hobby to his profile

POST /users/{id}/hobbies or POST /profile/hobbies

CodePudding user response：

It's a joy to see people paying attention to their API design in terms of URI and responses. An API that is not well designed is going to quickly die since people will avoid using them.

Even if it's not going to be public and no one will use it aside from yourself or your team, think of your colleagues and your future self and take some time to think about how your URIs will look like.

Back to your question my friend, according to the hands-on restful API design patterns and best practices book, that I invite you to read,the REST API is composed of four unique archetypes, as follows:

• Document: The document is the base for a resource representation with a field and link-based structure.

 https://api-test.​lufthansa.com/​v1/profiles
 https:/​/api-test.lufthansa.​com/​v1/​profiles/​customers

• Collection: A collection is also a resource, and it is a directory of resources managed by the API providers or servers.

https:/​/api-​test.​lufthansa.​com/​v1/​profiles/​customers/accountbalance
https:/​/api-​test.lufthansa.​com/​v1/​profiles/​customers/memberstatus

• Stores: A store is a resource repository managed by the client. The store allows the API client to put resources in, choose URIs for the resources that get added, get them out, and delete them when it decides.

http:/​/api.example.com/cart-management/users/{id}/carts
http:/​/api.​example.​com/​song-​management/​users/​{id}/playlists

• Controller: Controller resources are similar to executable methods, with parameters and return values. REST API relies on controller resources to perform application-specific actions that do not come under any of the CRUD methods.

POST /alerts/245245/resend

So, in your case, you can follow the API design of GitHub API. Look how they are retrieving the projects of an organisation. Yours would look this way:

PUT /users/{id}/profile-pic
POST /users/{id}/hobbies

I'm sorry for making it long, I wanted to base my perspective on something concrete.

CodePudding user response：

When an authenticated user wishes to access a resource which he exclusively owns, it seems redundant to specify the user id in the URL path.

It shouldn't; the semantics of a resource identifier and the semantics of an Authorization header are different.

The fact that only Bob can get a copy of /profile/Bob is a matter of access policy, not message semantics.

Review Fielding's definition of resource. "Bob's profile" and "Alice's profile" are distinct nameable information (assuming for the moment that Bob and Alice are themselves distinct) and therefore should have different identifiers.

That's the "RESTful" answer.

In practice, HTTP has special rules about authentication, and the handling of authenticated requests means that you'll probably "get away with" treating the Authorization header as part of the identifier of the resource (particularly in the case where an authorized user is only allowed to access their own resource hierarchy).