REST API Two seperate resources to create a user?

Question

Currently building a REST API and one of the functions of it will be to create users. There are two ways my application will create users:

• Register, users add themselves with the usual data: email, password, username, date of birth.
• Manual creation, admin adds a user with usual data AND any extra data as required.

My setup is a users table, users_metadata table and users_permissions table, as well as a few others. The email and password are stored in the users table, the username and date of birth in the users_metadata table. When manually creating a user other metadata and the user's permissions, as well as data in the other tables, can be changed.

Would it be better to have two different resources to handle creating a user?

Answer 1

Would it be better to have two different resources to handle creating a user?

I wouldn't create two different resources that both represent the user and both model its creation process. Since a user is a user, in my opinion they should be created trough the same resource.

Manual creation, admin adds a user with usual data AND any extra data as required .

When manually creating a user other metadata and the user's permissions , as well as data in the other tables, can be changed.

If it makes sense, you could model this extra data as a separate (sub)resource. The same goes for permissions. This sub resource can then have its own URL (for instance /users/{id}/meta and /users/{id}/permissions ) to which the client issues separate POST requests, or it can be nested in the data structure that is sent to the API, like so:

{
    "name": "John",
    "email-address": "john@doe.com",
    "permissions": {
        "read": true,
        "write": false
    },
    "meta-data": {
        "date-of-birth": "2000-01-01"
    }
}

The approach with separate sub resources at their own URLs makes access control and validation a bit easier. On the other hand, it puts a bigger burden on the client. It can also put you in the position where an admin creates a user, the basic information is saved, but there is an error saving permissions; depending on your use case you may or may not need to somehow handle that automatically.

The approach where the sub resources are nested in the data structure makes the logic to handle the POST request a bit more complex, but it does make the client side of things easier and gives you the option to make the whole action atomic by wrapping it in a transaction and rolling back if anything goes wrong.

Note: These two approaches are not mutually exclusive; you can do both if you want.

Which of these approaches is best will depend on how many sub resources there are, how complex they are and how complex the access control to the sub resources is; the more sub resources there are and/or the more complex access control is, the more likely I would be to setup different URLs for the sub resources.

In this specific case, I would net the sub resources in the data structure and have the clients POST all the data at once.