User roles API

General remarks

This documents outlines the API design for user management. The concepts are based on the organization wireframes and the static user roles the platform is going to support initially.

Some of the endpoints have already been implemented with the organization API, but need to be extended to support assignment and management of user roles.

The roles of a user are represented as:

"roles": {
    "org_admin": true,
    "projects": [
        {
            "id": 1,  // the project ID
            "manager": false,
            "collector": true
        }
    ]
}

The structure is used both in request and response payloads.

API endpoints

Organization roles

List all users

This endpoint is already implemented. User's roles have to be added to the response.

Request

GET /<api_version>/organizations/<organization_slug>/users/

Successful response

Returns a list of all users in an organization.

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "username": "p_smith",
        "first_name": "Prudence",
        "last_name": "Smith",
        "email": "[email protected]",
        "email_verified": true,
        "roles": {
            "org_admin": true,
            "projects": [
                {
                    "id": 1,  // the project ID
                    "name": "Kibera",
                    "manager": false,
                    "collector": true
                }
            ]
        }
    }
]

Errors

• 401 Unauthorized: No user is signed in.
• 403 Forbidden: The user is not allowed to access the list.
• 404 Not found:
  • The organization was not found.
  • The user has no access to the organization.

Add an existing user to an organization

Request

This endpoint is partially implemented. Currently it accepts only one user at a time. I suggest to make this flexible so one can either POST a single user or an array of users for bulk uploads.

POST /<api_version>/organizations/<organization_slug>/users/

[
    {
        "username": "nsmith",
        "roles": {
            "org_admin": false,
            "projects": {
                "id": 1,
                "manager": false,
                "collector": true
            }
        }
    },
    {
        "username": "bmiller"
    }
]

In the request body, role names may be omitted, in which case role flags default to false. One can thus use the following to add user nsmith to project 1 as a "normal" user:

[
    {
        "username": "nsmith",
        "roles": {
            "projects": {
                "id": 1,
            }
        }
    }
]

Successful response

The response contains the users that have been added to the organization as well as those that don't exist.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "added": [
        {
            "username": "nsmith",
            "first_name": "Nicole",
            "last_name": "Smith",
            "email": "[email protected]",
            "email_verified": true,
            "roles": {
                "org_admin": false,
                "projects": {
                    "id": 1,
                    "name": "Kibera",
                    "manager": false,
                    "collector": true
                }
            }
        }
    ],
    "not_found": [
        {
            "username": "bmiller",
        }
    ]
}

Errors

• 401 Unauthorized: No user is signed in.
• 403 Forbidden: The user is not allowed to add users to the organization.
• 404 Not found:
  • The organization was not found
  • The user has no access to the organization.

Update organization roles of a single user

Request

PATCH /<api_version>/organizations/<organization_slug>/users/<username>

{
    "roles": {
        "org_admin": false,
        "projects": {
            "id": 1,
            "manager": false,
            "collector": true
        }
    }
}

Successful response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "username": "nsmith",
    "first_name": "Nicole",
    "last_name": "Smith",
    "email": "[email protected]",
    "email_verified": true,
    "roles": {
        "org_admin": false,
        "projects": {
            "id": 1,
            "name": "Kibera",
            "manager": false,
            "collector": true
        }
    }
}

Errors

• 401 Unauthorized: No user is signed in.
• 403 Forbidden: The user is not allowed to update user roles users of the organization.
• 404 Not found:
  • The organization was not found.
  • The user has no access to the organization.
  • The user was not found.

Delete a single user from an organization

Request

DELETE /<api_version>/organizations/<organization_slug>/users/<username>/

Successful response

HTTP/1.1 204 No Content

Errors

• 401 Unauthorized: No user is signed in.
• 403 Forbidden: The user is not allowed to remove users from the organization.
• 404 Not found:
  • The organization was not found.
  • The user has no access to the organization.
  • The user was not found.

Project roles

List all users in a project

Request

GET /<api_version>/organizations/<organization_slug>/projects/<project_slug>/users/

Successful response

A list of users and their roles for the given project.

HTTP1.1 200 Ok

[
    {
        "username": "p_smith",
        "first_name": "Prudence",
        "last_name": "Smith",
        "email": "[email protected]",
        "email_verified": true,
        "roles": {
            "manager": false,
            "collector": true
        }
    }
]

Errors

• 401 Unauthorized: No user is signed in.
• 403 Forbidden: The user is not allowed to list users in the project.
• 404 Not found:
  • The organization or project was not found.
  • The user has no access to the organization or organization.

Add new users to a project with specified roles

Request

The request payload is either a single user object or an array of user objects.

POST /<api_version>/organizations/<organization_slug>/projects/<project_slug>/users/

[
    {
        "username": "nsmith",
        "roles": {
            "manager": false,
            "collector": true
        }
    },
    {
        "username": "bmiller",
        "roles": {
            "manager": true,
            "collector": false
        }
    }
]

Successful response

Unless the requesting user is not allowed to add users or the organization or project were not found, the response will always be HTTP 200 OK. Errors with the request payload are detailed in the response; for instance, a list of users that do not exist in the data base is available in the not_found property.

HTTP1.1 200 Ok

{
    "added": [
        {
            "username": "nsmith",
            "first_name": "Nicole",
            "last_name": "Smith",
            "email": "[email protected]",
            "email_verified": true,
            "roles": {
                "manager": false,
                "collector": true
            }
        }
    ],
    "not_found": [
        {"username": "bmiller"}
    ]
}

Errors

• 401 Unauthorized: No user is signed in.
• 403 Forbidden: The user is not allowed to add users to the project.
• 404 Not found:
  • The organization or project was not found.
  • The user has no access to the organization or organization.
  • The user to update was not found.

Update roles of a single user

Request

PATCH /<api_version>/organizations/<organization_slug>/projects/<project_slug>/users/<username>/

{
    "roles": {
        "manager": false,
        "collector": true
    }
}

Successful response

HTTP1.1 200 Ok

{
    "username": "nsmith",
    "first_name": "Nicole",
    "last_name": "Smith",
    "email": "[email protected]",
    "email_verified": true,
    "roles": {
        "manager": false,
        "collector": true
    }
}

Errors

• 401 Unauthorized: No user is signed in.
• 403 Forbidden: The user is not allowed to list users in the project.
• 404 Not found:
  • The organization or project was not found.
  • The user has no access to the organization or project.

Remove a single user from a project

Request

DELETE /<api_version>/organizations/<organization_slug>/projects/<project_slug>/users/<username>/

Successful response

HTTP1.1 204 No Content

Errors

• 401 Unauthorized: No user is signed in.
• 403 Forbidden: The user is not allowed to remove users from the project.
• 404 Not found:
  • The organization or project was not found.
  • The user has no access to the organization or organization.
  • The user to be removed was not found.

Proposed future API endpoints

The endpoints listed here are proposed for future implementation, but their exact form is up for discussion. In particular, there isn't a very good standardised way of doing bulk updates in REST APIs, so we need to talk about how these are going to work in some detail.

Organization roles

Bulk update organization roles of many user

Request

Request body is an array of users with new roles for each user that is updated.

PATCH /<api_version>/organizations/<organization_slug>/users/

[
    {
        "username": "nsmith",
        "roles": {
            "org_admin": false,
            "projects": {
                "id": 1,
                "manager": false,
                "collector": true
            }
        }
    },
    {
        "username": "bmiller",
        "roles": {
            "org_admin": false,
            "projects": {
                "id": 1,
                "manager": false,
                "collector": true
            }
        }
    }
]

Successful response

Unless the requesting user is not allowed to update permissions or the organization was not found, the response will always be HTTP 200 OK. Errors with the request payload are detailed in the response; for instance, a list of users that do not exist in the data base is available in the not_found property.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "added": [
        {
            "username": "nsmith",
            "first_name": "Nicole",
            "last_name": "Smith",
            "email": "[email protected]",
            "email_verified": true,
            "roles": {
                "org_admin": false,
                "projects": {
                    "id": 1,
                    "name": "Kibera",
                    "manager": false,
                    "collector": true
                }
            }
        }
    ],
    "not_found": [
        {
            "username": "bmiller"
        }
    ]
}

Errors

• 401 Unauthorized: No user is signed in.
• 403 Forbidden: The user is not allowed to update user roles users of the organization.
• 404 Not found:
  • The organization was not found.
  • The user has no access to the organization.

Bulk delete users from an organization

Request

The request payload contains a list of users that will be removed from the organization.

DELETE /<api_version>/organizations/<organization_slug>/users/

[ {"username": "nsmith"}, {"username": "bmiller"} ]

Successful response

Unless the requesting user is not allowed to remove users or the organization was not found, the response will always be HTTP 200 OK. Errors with the request payload are detailed in the response; for instance, a list of users that do not exist in the data base is available in the not_found property. Success HTTP/1.1 200 Ok

{ "removed": [ {"username": "nsmith"} ], "not_found": [ {"username": "bmiller"} ] }

Errors 401 Unauthorized: No user is signed in. 403 Forbidden: The user is not allowed to remove users from the organization. 404 Not found: The organization was not found. The user has no access to the organization.

Project roles

Bulk update roles of many users

Request

PATCH /<api_version>/organizations/<organization_slug>/projects/<project_slug>/users/

[
    {
        "username": "nsmith",
        "roles": {
            "manager": false,
            "collector": true
        }
    },
    {
        "username": "bmiller",
        "roles": {
            "manager": true,
            "collector": false
        }
    }
]

Successful response

Unless the requesting user is not allowed to update users or the organization or project were not found, the response will always be HTTP 200 OK. Errors with the request payload are detailed in the response; for instance, a list of users that do not exist in the data base is available in the not_found property.

HTTP1.1 200 Ok

{
    "updated": [
        {
            "username": "nsmith",
            "first_name": "Nicole",
            "last_name": "Smith",
            "email": "[email protected]",
            "email_verified": true,
            "roles": {
                "manager": false,
                "collector": true
            }
        }
    ],
    "not_found": [
        {"username": "bmiller"}
  ]
}

Errors

• 401 Unauthorized: No user is signed in.
• 403 Forbidden: The user is not allowed to update users in the project.
• 404 Not found:
  • The organization or project was not found.
  • The user has no access to the organization or organization.

Bulk remove many users from a project

Request

The request payload contains a list of user to be removed from the project.

DELETE /<api_version>/organizations/<organization_slug>/projects/<project_slug>/users/
[
    {"username": "nsmith"},
    {"username": "bmiller"}
]

Successful response

Unless the requesting user is not allowed to remove users or the organization or project were not found, the response will always be HTTP 200 OK. Errors with the request payload are detailed in the response; for instance, a list of users that do not exist in the data base is available in the not_found property.

HTTP1.1 200 Ok

{
    "removed": [
        {"username": "nsmith"}
    ],
    "not_found": [
        {"username": "bmiller}
    ]
}

Errors

• 401 Unauthorized: No user is signed in.
• 403 Forbidden: The user is not allowed to remove users from the project.
• 404 Not found:
  • The organization or project was not found.
  • The user has no access to the organization or organization.