Table of Contents
[API] Users
All of these routes need admin authentication.
GET /users 🔒
Returns all users as a JSON array.
Parameters
s: [optional] Searchstring. If provided, returns only those users whose name match the search term.
Response
200 All found users.
500 A server error occured.
Example
Request:
curl http://localhost:8082/api/v1/users
Result:
[
{
"id": 1,
"name": "That Guy",
"username": "user1",
"password": "",
"email": "thatguy@example.com",
"isAdmin": true,
"created": 1516713623,
"updated": 1516713642
},
{
"id": 2,
"name": "That Other Guy",
"username": "user2",
"password": "",
"email": "thatotherguy@example.com",
"isAdmin": true,
"created": 1516713623,
"updated": 1516713642
}
]
Password hashes are obfuscated for security reasons.
GET /users/:id 🔒
Returns a JSON-Object with all informations about a single user.
Parameters
id: The ID of the user you want to retrieve.
Response
200 The user.
400 ID is invalid or empty.
404 The user does not exist.
500 A server error occured.
PUT /users 🔒
Creates a new user.
Payload
Expects a JSON user object. Either directly as a JSON-object see the example below or as a string via the form value user. When sending as JSON, you need to include the Content-Type: application/json;charset=utf-8-Header.
You need to specify at least a username and a password!
Response
200 The user was successfully inserted. Returns the newly created user.
400 No user payload was provided or the title is empty. Returns a more specific message.
500 A server error occured.
Example
Request:
curl \
-H 'Authorization: Bearer <YOUR TOKEN HERE>' \
-X PUT \
-d user='{"name": "Noom", "username": "user24", "password": "1234"}' \
http://localhost:8082/api/v1/users
Response:
{
"id": 26,
"name": "Noom",
"username": "user24",
"password": "",
"email": "",
"isAdmin": false,
"created": 1516974531,
"updated": 1516974531
}
DELETE /users/:id 🔒
Deletes a user by its ID.
Parameters
ID: The ID of the user you want to delete.
Response
200 The user was successfully deleted.
400 ID is invalid or empty.
404 No user with this ID exists.
500 An error occured while deleting.
Example
Request:
curl \
-H 'Authorization: Bearer <YOUR TOKEN HERE>' \
-X DELETE \
http://localhost:8082/api/v1/users/26
Response:
{"message":"success"}
POST /users/:id 🔒
Updates an user by its ID. Returns the newly updated user.
Parameters
ID: The ID of the user you want to update.
Payload
Expects a JSON user object see inserting an user.
Response
200 The user was successfully updated.
400 User payload is empty, not valid or the ID is invalid.
404 No user with this ID exists.
500 An error occured while updating.
Example
Request:
curl \
-H 'Authorization: Bearer <YOUR TOKEN HERE>' \
-X POST \
-d user='{"name": "Lorem Impsum"}' \
http://localhost:8082/api/v1/users/130
Response:
{
"id": 130,
"name": "Lorem Impsum",
"created": 1512480155,
"updated": 1512651507
}
POST /users/:id/password 🔒
Updates a users password.
An admin can update any user's password, but a normal user can only update its own.
Parameters
ID: The ID of the user whichs password you want to update.
Payload
Expects a JSON user object see inserting an user.
Response
200 The user was successfully updated.
400 User payload is empty, not valid or ID is invalid.
404 No user with this ID exists.
500 An error occured while updating.
Example
Request:
curl \
-H 'Authorization: Bearer <YOUR TOKEN HERE>' \
-X POST \
-d password='12345' \
http://localhost:8082/api/v1/users/130/password
Response:
{"message":"The password was updated successfully"}