Users /users
¶
You can manage user data by using /users
endpoint.
It provides users management: creation, data retrieval, modification, removal and roles associations.
Create a user¶
You can create user data by using POST /users
endpoint.
Users data must be specified inside body JSON data.
Request body structure is:
{
"data": {
"type": "users",
"attributes": {}
}
}
-
POST
/users
¶
Example request (create user john doe):
POST /users HTTP/1.1
Host: example.com
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
{
"data": {
"type": "users",
"attributes": {
"username": "johndoe",
"password": "j04nd0e",
"uname": "johndoe"
}
}
}
Example above show all required attributes.
Expected response is HTTP/1.1 201 OK
, with application/vnd.api+json
body data representing the user just created.
When user already exists or data is not valid (i.e. data lacks of required fields), POST fails and response is 400 Bad Request - Invalid data
.
Successful response example follows:
HTTP/1.1 201 OK
Content-Type: application/vnd.api+json
{
"data": {
"id": 19283,
"type": "users",
"attributes": {
"username": "johndoe",
"password": "j04nd0e",
"uname": "johndoe",
"created_by": 1,
"modified_by": 1,
"created": "2016-12-13T12:08:02+00:00",
"modified": "2016-12-13T12:08:02+00:00"
},
"relationships": {
"roles": {
"links": {
"related": "http://example.com/users/19283/roles",
"self": "http://example.com/users/19283/relationships/roles"
}
}
}
},
"links": {
"self": "http://example.com/users",
"home": "http://example.com/home"
}
}
data.attributes
object contains more internal attributes.
Get user data¶
You can obtain user data by using GET /users
and GET /users/(user_id)
endpoint.
-
GET
/users
¶
It returns a collection of users:
- use
id
query string parameter to retrieve a single user by id- use
id
query string parameter androles
token to retrieve user roles by user id
-
GET
/users/
(user_id)¶
Example request (get users):
GET /users HTTP/1.1
Host: example.com
Accept: application/vnd.api+json
Example response:
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"id": 19283,
"type": "users",
"attributes": {
"username": "johndoe",
"name": "john",
"surname": "doe"
}
}
],
"links": {
"self": "http://example.com/users/19283",
"home": "http://example.com/home",
"first": "http://example.com/users",
"last": "http://example.com/users",
"prev": null,
"next": null
},
"meta": {
"pagination": {
"count": 1,
"page": 1,
"page_count": 1,
"page_items": 1,
"page_size": 20
}
}
}
data
is an array of objects; in this example, you see only one.
data.attributes
object contains more internal attributes.
-
GET
/users/
(user_id)/roles
¶
You can obtain user roles by using GET /users/(user_id)/roles
endpoint.
Example request (get user johndoe roles):
GET /users/19283/roles HTTP/1.1
Host: example.com
Accept: application/vnd.api+json
Example response:
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"id": "7",
"type": "roles",
"attributes": {
"name": "dummy role",
"description": null,
"unchangeable": false,
"created": "2016-12-13T11:28:32+00:00",
"modified": "2016-12-13T11:28:32+00:00"
},
"links": {
"self": "http://example.com/roles/7"
},
"relationships": {
"users": {
"links": {
"related": "http://example.com/roles/7/users",
"self": "http://example.com/roles/7/relationships/users"
}
}
}
}
],
"links": {
"self": "http://example.com/users/19283/roles",
"home": "http://example.com/home",
"first": "http://example.com/users/19283/roles",
"last": "http://example.com/users/19283/roles",
"prev": null,
"next": null
},
"meta": {
"pagination": {
"count": 1,
"page": 1,
"page_count": 1,
"page_items": 1,
"page_size": 20
}
}
}
Modify a user¶
You can modify a user by using PATCH /users/(user_id)
endpoint.
-
PATCH
/users/
(user_id)¶
Example request (modify user john doe):
In this example, purpose is modifying ‘johndoe’ user’s name and surname from ‘john doe’ to ‘Johnny Doe’.
PATCH /users/19283 HTTP/1.1
Host: example.com
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
{
"data": {
"id": 19283,
"type": "users",
"attributes": {
"name" : "Johnny",
"surname" : "Doe"
}
}
}
Response 200 OK is expected.
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"id": 19283,
"type": "users",
"attributes": {
"username": "johndoe",
"name": "Johnny",
"surname": "Doe"
},
"relationships": {
"roles": {
"links": {
"related": "http://example.com/users/19283/roles",
"self": "http://example.com/users/19283/relationships/roles"
}
}
}
},
"links": {
"self": "http://example.com/users/19283",
"home": "http://example.com/home"
}
}
data.attributes
object contains more internal attributes.
Remove a user¶
You can delete a user by using DEL /users/(user_id)
endpoint.
-
DELETE
/users/
(user_id)¶
Example request (delete user john doe):
Note: in this example user id is 19283.
DELETE /users/19283 HTTP/1.1
Host: example.com
Expected response is 204 No Content
. When user is not found, response is 404 Not Found
.
HTTP/1.1 204 No Content
Add a role¶
You can add a role by using POST /users/(user_id)/relationships/roles
endpoint.
(user_id)
is a placeholder for user object id.
You specify role id inside JSON body passed to request.
-
POST
/users/
(user_id)/relationships/roles
¶
Example request (add role 7 to john doe user):
In this example, purpose is adding a role (id 7) to ‘johndoe’ user (id 19283).
POST /users/19283/relationships/roles HTTP/1.1
Host: example.com
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
{
"data": {
"type": "roles",
"id": 7
}
}
Response 200 OK is expected.
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"links": {
"self": "http://example.com/users/19283/relationships/roles",
"home": "http://example.com/home"
}
}
Remove a role¶
You can remove a role by using DELETE /users/(user_id)/relationships/roles
endpoint.
(user_id)
is a placeholder for user object id.
You specify role id inside JSON body passed to request.
-
DELETE
/users/
(user_id)/relationships/roles
¶
Example request (remove role 7 to john doe user):
In this example, purpose is removing a role (id 7) from ‘johndoe’ user (id 19283).
DELETE /users/19283/relationships/roles HTTP/1.1
Host: example.com
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
{
"data": {
"type": "roles",
"id": 7
}
}
Response 200 OK is expected.
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"links": {
"self": "http://example.com/users/19283/relationships/roles",
"home": "http://example.com/home"
}
}