Search code examples
apirestrestful-architectureendpoint

Restful API design: how should user's and authority's endpoints be?

Based on similar questions, i came to the conclusion that the most convenient way to design this endpoints to GET requests should be something like: 

GET /v3/users/
GET /v3/users/{userId}
GET /v3/users/{userId}/authorities
GET /v3/users/authorities/{authId}

My question is how should be the next endpoints:

1. Create authorities
POST /v3/users/authorities 
POST /v3/users/{userId}/authorities 

2. Update authorities
PUT/PATCH /v3/users/authorities/{authId} 
PUT/PATCH /v3/users/{userId}/authorities/{authId} 

3. Delete authorities
DELETE /v3/users/authorities/{authId} 
DELETE /v3/users/{userId}/authorities/{authId}

What do you think? Intuitively, i go with first option on all cases but maybe is not the nicest thing passing the userId from body (i see it nicer passing it from url). Or should i implement both endpoints maybe?

Solution

  • Second approach is cleaner and more standard.

    PUT/PATCH/POST/DELETE.. /v3/users/authorities/{authId} - [1]
PUT/PATCH/POST/DELETE.. /v3/users/{userId}/authorities/{authId} -[2]

    Here, for example, if you pass authId in uri, why not userId ? The standard you will be following here is "resource/{uniqueId}/attribute/{uniqueId}". Ideally in your back-end code, you first look up for the specific resource, and then look up specific attribute(s) for the same resource with the keys/ids passed in the uri. Id is omitted when the action is going to affect all the resources!

    If you use the approach [1], it looks like you are trying to add/update/delete an authority for ALL users! Definitely that is not the case.

    It is doable to send the userId in the form/post data, but not the correct approach. In your form/post data, you should send the values that are going to be added/updated (in case of PUT/POST). Something like {authType: 'Admin', isGlobal: true, effectiveFrom: '12/12/2015'}. Obviously, userId does not fit here.