PUT list to a mapping collection. Only id array in request body?

Question

I'm designing a REST interface for my service. My service will be Role and Permission based. Therefor a Role will contain Permissions.

Meaning a Role will have a collection of Permissions -> roles/1/permissions

Now I would like to change the set of Permissions for a Role. As I understand, a correct request for this would be:

PUT roles/1/permissions
[
    {
        id: 1,
        permissionName: "read"
    }, {
        id: 2,
        permissionName: "write"
    }, {
        id: 3,
        permissionName: "delete"
    }
]

As this basically only maps existing permissions (/permissions) to a role, there is a lot of unnecessary information sent. Especially if this example would contain a resource which is much more detailed as a Permission.

Would it be okay to only send an array of ids in the body?

PUT roles/1/permissions
{
    ids:[1,2,3]
}

I would reach the same, with only the information I actually need. Is there a problem with this approach? I'm afraid that this might hurting the stateless principle of REST.

How is it any less-stateless than the other? It’s harder to reason about on the wire since you lose human-grokkable info, but that may now matter to you. REST is a principle-make your endpoints be what you need. — Dave Newton, Nov 07 '17 at 13:22

score 1 · Answer 1 · answered Nov 07 '17 at 09:20

1

Your REST API is completely fine and it does not violate the stateless principle in any way. Your REST API will be using a different resource model for GET and PUT methods, which is also fine.

answered Nov 07 '17 at 09:20

Adam Siemion

15,569
7
58
92

score 1 · Accepted Answer · edited Oct 07 '21 at 12:12

Sending the permission identifiers is just fine to create a link between the a given role and a set of permissions.

On server side, you should validate the permission identifiers and return a 422 if they are invalid. See this answer for further details.

The stateless constraint determines that each request must contain all of the information necessary to be understood by the server, rather than be dependent on the server remembering prior requests. And session state should be handled entirely by the client:

5.1.3 Stateless

[...] each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server. Session state is therefore kept entirely on the client. [...]

Sending only the permission identifiers won't break the stateless constraint.

For more details on the stateless constraint, refer to this answer.

PUT list to a mapping collection. Only id array in request body?

2 Answers2