Users API

A user is a valid login for a secured application.

Users can also be labelled with ‘isAdmin’, which marks them as able to access back-end endpoints not required for standard users.

User Creation

POST /v1/users/sign-up

Create a new User. Please note that only administrator users can access this endpoint.

Request Headers:
 
Status Codes:

http

POST /users/sign-up HTTP/1.1
Host: localhost:8080
Content-Type: application/json

{
    "username": "aesel",
  "password": "guest",
  "email": "test@test.com",
  "isAdmin": false,
  "isActive": true,
  "favoriteProjects": [],
  "favoriteScenes": []
}

curl

curl -i -X POST http://localhost:8080/users/sign-up -H 'Content-Type: application/json' --data-raw '{"email": "test@test.com", "favoriteProjects": [], "favoriteScenes": [], "isActive": true, "isAdmin": false, "password": "guest", "username": "aesel"}'

User Retrieval

GET /v1/users/(key)

Get a User by ID.

Status Codes:

http

GET /users/{key} HTTP/1.1
Host: localhost:8080

curl

curl -i 'http://localhost:8080/users/{key}'

response

HTTP/1.1 200 OK
Location: http://localhost:8080/users/{key}

{
    "id": "5c1aecad5728a474b669a880",
    "username": "demo2",
    "email": "test3@test.com",
    "isAdmin": false,
    "isActive": true,
    "favoriteProjects": [],
    "favoriteScenes": []
}

User Update

PUT /v1/users/(key)

Update an existing User’s basic (String or number) attributes. This endpoint cannot update list attributes, including favorite projects and favorite scenes. These can be updated by the respective HTTP endpoints.

Request Headers:
 
Status Codes:

http

PUT /users/{key} HTTP/1.1
Host: localhost:8080
Content-Type: application/json

{
    "username": "guest2",
  "password": "guest2",
  "email": "test2@test.com",
  "isAdmin": false,
  "isActive": true,
  "favoriteProjects": [],
  "favoriteScenes": []
}

curl

curl -i -X PUT 'http://localhost:8080/users/{key}' -H 'Content-Type: application/json' --data-raw '{"email": "test2@test.com", "favoriteProjects": [], "favoriteScenes": [], "isActive": true, "isAdmin": false, "password": "guest2", "username": "guest2"}'

Add Favorite Project

PUT /v1/users/(key)/projects/(projectKey)

Atomically add a Project Key to the favoriteProjects list of the user.

Request Headers:
 
Status Codes:

http

PUT /users/{key}/projects/{projectKey} HTTP/1.1
Host: localhost:8080

curl

curl -i -X PUT 'http://localhost:8080/users/{key}/projects/{projectKey}'

Remove Favorite Project

DELETE /v1/users/(key)/projects/(projectKey)

Atomically remove a Project Key from the favoriteProjects list of the user.

Request Headers:
 
Status Codes:

http

DELETE /users/{key}/projects/{projectKey} HTTP/1.1
Host: localhost:8080

curl

curl -i -X DELETE 'http://localhost:8080/users/{key}/projects/{projectKey}'

Add Favorite Scene

PUT /v1/users/(key)/scenes/(sceneKey)

Atomically add a Scene Key to the favoriteScenes list of the user.

Request Headers:
 
Status Codes:

http

PUT /users/{key}/scenes/{sceneKey} HTTP/1.1
Host: localhost:8080

curl

curl -i -X PUT 'http://localhost:8080/users/{key}/scenes/{sceneKey}'

Remove Favorite Scene

DELETE /v1/users/(key)/scenes/(sceneKey)

Atomically remove a Scene Key from the favoriteScenes list of the user.

Request Headers:
 
Status Codes:

http

DELETE /users/{key}/scenes/{sceneKey} HTTP/1.1
Host: localhost:8080

curl

curl -i -X DELETE 'http://localhost:8080/users/{key}/scenes/{sceneKey}'

Make User Admin

PUT /v1/users/(key)/admin

Make a user an administrator.

Request Headers:
 
Status Codes:

http

PUT /users/{key}/admin HTTP/1.1
Host: localhost:8080

curl

curl -i -X PUT 'http://localhost:8080/users/{key}/admin'

Make User Non-Admin

DELETE /v1/users/(key)/admin

Remove administrator access from a user.

Request Headers:
 
Status Codes:

http

DELETE /users/{key}/admin HTTP/1.1
Host: localhost:8080

curl

curl -i -X DELETE 'http://localhost:8080/users/{key}/admin'

Activate User

PUT /v1/users/(key)/active

Activate a user.

Request Headers:
 
Status Codes:

http

PUT /users/{key}/active HTTP/1.1
Host: localhost:8080

curl

curl -i -X PUT 'http://localhost:8080/users/{key}/active'

Deactivate User

DELETE /v1/users/(key)/active

Deactivate a user, revoking all access until they are reactivated.

Request Headers:
 
Status Codes:

http

DELETE /users/{key}/active HTTP/1.1
Host: localhost:8080

curl

curl -i -X DELETE 'http://localhost:8080/users/{key}/active'

User Query

GET /v1/users/

Query for users by attribute.

Status Codes:

http

GET /users/?username=aesel HTTP/1.1
Host: localhost:8080

curl

curl -i 'http://localhost:8080/users/?username=aesel'

response

HTTP/1.1 200 OK
Location: http://localhost:8080/users/{key}

{
    "id": "5c1aecad5728a474b669a880",
    "username": "demo2",
    "email": "test3@test.com",
    "isAdmin": false,
    "isActive": true,
    "favoriteProjects": [],
    "favoriteScenes": []
}

User Delete

DELETE /v1/users/(key)

Delete a user by ID.

Status Codes:

http

DELETE /users/{key} HTTP/1.1
Host: localhost:8080

curl

curl -i -X DELETE 'http://localhost:8080/users/{key}'