I am having some trouble coming up with a restful url structure for my admin. In the admin I have "users" but users have subtypes as well - for example: internal staff, client managers, client staff - and each of these users have particular properties. For the scenario of creating a new user it would be easy enough to have them all just POST /users and include an attribute "type" that says what type of user it is. However, this solution doesn't seem quite right when it comes to documenting this endpoint. Each user type has different attributes required only for that user type just to name a few:
Although each of these users have a common set of values like username, password, email, it feels like creating them all to the same endpoint will be confusing when we get to documenting because it will be unclear which fields are required for which user type (unless you look at the code). My other thought is to make endpoints for each user type like:
POST /users/internal_staff
POST /users/client_supervisors
POST /users/client_staff
I'd love to hear from people who have dealt with a structure issue like this and what they found was the most reasonable solution.
Your approach of POST /users is exactly spot on. Creating three different end points is just like repeating your code in all three different methods.
As you have clearly mentioned, you will need to take care of documentation when you have the same endpoint for three different employee subtypes. Best option is to create Enum which contain records of different type of Employees and publish it. And as a part of documentation you will need to mention possible value for employee type. (E.g. that can be internal_staff_member, client_supervisor or client_staff).
If you receive any request with different type (other than above mentioned values), you will need to throw an exception saying 'Invalid Employee Type. Employee type can be..'.
In the documentation, you will need to mention some business rules very clearly stating which attributes are compulsory for which type of employee. (E.g. when employee type is - client staff, then - payload must contain following attributes: department id, company id, address, hours of operation. etc).
To support these business rules and validations, we are using custom annotations (using java and spring).