Examples
Contents
- Get a list of all users
- Get a list of emails of all users
- Get all possible data about all users
- Get all possible data about all users, whose name contains "sam"
- Create a new user
- Create two more users
- Update user data
- Mark users deleted
- Physically delete users
- Understanding validation errors
- Understanding fatal errors
Get a list of all users
No modifiers
Make a GET request to the /users endpoint:
GET /users HTTP/1.1 Host: api.geoop.com Authorization: Bearer oJ_7Hj.f-F3f.kL X-Version: 1.0
The response object will contain a collection of user items, each having the default set of fields:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
X-Version: 1.0
{
"result": "success",
"users": [
{
"id": 12,
"firstName": "John",
"lastName": "Doe",
"companyName": "Sample Company",
"email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
"phone": "+15559282001",
"mobile": "+15554308211",
"hourlyRate": 25,
"active": 1,
"deleted": false,
"colour": "#FBA710",
"isAssignable": true,
"role": {
"id": 16
},
"account": {
"id": 22
},
"status": {
"message": "I am on my way to the client.",
"timestamp": "2014-01-17T00:21:43+00:00"
}
},
{
"id": 14,
"firstName": "Krissy",
"lastName": "Hibbard",
"companyName": "Sample Company",
"email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
"phone": "+15559282001",
"mobile": "+15553129458",
"hourlyRate": 40,
"active": 1,
"deleted": false,
"colour": null,
"isAssignable": true,
"role": {
"id": 2
},
"account": {
"id": 22
},
"status": {
"message": "Working from home today.",
"timestamp": "2014-02-03T09:56:06+00:00"
}
},
{
"id": 17,
"firstName": "Kirk",
"lastName": "Boatright",
"companyName": "Sample Company",
"email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
"phone": "+15559282001",
"mobile": "+15559629350",
"hourlyRate": 25,
"active": 1,
"deleted": false,
"colour": null,
"isAssignable": true,
"role": {
"id": 16
},
"account": {
"id": 22
},
"status": {
"message": "I am working...",
"timestamp": "2014-02-03T14:31:57+00:00"
}
}
],
"metadata": {
"page": 1,
"pagesCount": 5,
"recordsPerPage": 3,
"recordsCount": 14
}
}
Note that the role and account parameters are simplified associated items, not fields.
Get a list of emails of all users
Apply fields modifier
We make a GET request to the /users endpoint and add a fields modifier:
GET /users?fields=email HTTP/1.1 Host: api.geoop.com Authorization: Bearer oJ_7Hj.f-F3f.kL X-Version: 1.0
The response object will contain a users collection of items, each having only the id and email fields:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
X-Version: 1.0
{
"result": "success",
"users": [
{
"id": 12,
"email": "This email address is being protected from spambots. You need JavaScript enabled to view it."
},
{
"id": 14,
"email": "This email address is being protected from spambots. You need JavaScript enabled to view it."
},
{
"id": 17,
"email": "This email address is being protected from spambots. You need JavaScript enabled to view it."
}
],
"metadata": {
"page": 1,
"pagesCount": 5,
"recordsPerPage": 3,
"recordsCount": 14
}
}
Note that the id field will always be present in the response items.
Get all possible data about all users
Apply a wildcard fields modifier
We make a GET request to the /users endpoint and add a wildcard fields modifier (we use * to display all fields of the root items and [*] to display all fields of the associated items):
GET /users?fields=*,[*] HTTP/1.1 Host: api.geoop.com Authorization: Bearer oJ_7Hj.f-F3f.kL X-Version: 1.0
The response object will contain a collection of items, each having all possible fields and associations:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
X-Version: 1.0
{
"result": "success",
"users": [
{
"id": 12,
"login": "jdoe_sample",
"firstName": "John",
"lastName": "Doe",
"companyName": "Sample Company",
"email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
"phone": "+15559282001",
"mobile": "+15554308211",
"hourlyRate": 25,
"active": 1,
"deleted": false,
"colour": "#FBA710",
"isAssignable": true,
"role": {
"id": 16,
"name": "Plumber"
},
"workgroups": [
{
"id": 6,
"name": "Field Workers"
},
{
"id": 7,
"name": "North Springfield"
}
],
"account": {
"id": 22,
"companyName": "Sample Company",
"licenses": 99,
"countryCode": 1,
"companyAccountCode": null
},
"status": {
"message": "I am on my way to the client.",
"timestamp": "2014-01-17T00:21:43+00:00"
}
},
{
"id": 14,
"login": "khibbard_sample",
"firstName": "Krissy",
"lastName": "Hibbard",
"companyName": "Sample Company",
"email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
"phone": "+15559282001",
"mobile": "+15553129458",
"hourlyRate": 40,
"active": 1,
"deleted": false,
"colour": null,
"isAssignable": false,
"role": {
"id": 2,
"name": "Manager"
},
"workgroups": [
{
"id": 5,
"name": "Office Staff"
},
{
"id": 7,
"name": "North Springfield"
},
{
"id": 8,
"name": "East Springfield"
},
{
"id": 9,
"name": "South Springfield"
}
],
"account": {
"id": 22,
"companyName": "Sample Company",
"licenses": 99,
"countryCode": 1,
"companyAccountCode": null
},
"status": {
"message": "Working from home today.",
"timestamp": "2014-02-03T09:56:06+00:00"
}
},
{
"id": 17,
"login": "kboatright_sample",
"firstName": "Kirk",
"lastName": "Boatright",
"companyName": "Sample Company",
"email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
"phone": "+15559282001",
"mobile": "+15559629350",
"hourlyRate": 25,
"active": 1,
"deleted": false,
"colour": null,
"isAssignable": true,
"role": {
"id": 16,
"name": "Plumber"
},
"workgroups": [
{
"id": 6,
"name": "Field Workers"
},
{
"id": 10,
"name": "West Springfield"
}
],
"account": {
"id": 22,
"companyName": "Sample Company",
"licenses": 99,
"countryCode": 1,
"companyAccountCode": null
},
"status": {
"message": "I am working...",
"timestamp": "2014-02-03T14:31:57+00:00"
}
}
],
"metadata": {
"page": 1,
"pagesCount": 5,
"recordsPerPage": 3,
"recordsCount": 14
}
}
Note that the items in the collection contain associated items formatted as objects, since we applied the [*] wildcard fields modifier.
Get all possible data about all users, whose name contains "sam"
Apply a wildcard fields modifier + a where modifier
We make a GET request to the /users endpoint and add a wildcard fields modifier plus a where modifier to enable filtering:
GET /users?fields=*,[*]&where=firstName+~+"sam" HTTP/1.1 Host: api.geoop.com Authorization: Bearer oJ_7Hj.f-F3f.kL X-Version: 1.0
The response object will contain a filtered collection of items, each having all possible fields and associations:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
X-Version: 1.0
{
"result": "success",
"users": [
{
"id": 12,
"login": "scorbett_sample",
"firstName": "Samuel",
"lastName": "Corbett",
"companyName": "Sample Company",
"email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
"phone": "+15559282001",
"mobile": "+15553284915",
"hourlyRate": 40,
"active": 1,
"deleted": false,
"colour": "#FBA710",
"isAssignable": false,
"role": {
"id": 2,
"name": "Manager"
},
"workgroups": [
{
"id": 5,
"name": "Office Staff"
},
{
"id": 10,
"name": "West Springfield"
},
{
"id": 11,
"name": "Central Springfield"
}
],
"account": {
"id": 22,
"companyName": "Sample Company",
"licenses": 99,
"countryCode": 1,
"companyAccountCode": null
},
"status": {
"message": "I temporarily don't accept any new jobs for West Springfield.",
"timestamp": "2014-01-27T14:21:19+00:00"
}
},
{
"id": 76,
"login": "rerdman_sample",
"firstName": "Rosamund",
"lastName": "Erdman",
"companyName": "Sample Company",
"email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
"phone": "+15559282001",
"mobile": "+15550293394",
"hourlyRate": 40,
"active": 1,
"deleted": false,
"colour": null,
"isAssignable": true,
"role": {
"id": 2,
"name": "Manager"
},
"workgroups": [
{
"id": 5,
"name": "Office Staff"
},
{
"id": 9,
"name": "South Springfield"
},
{
"id": 10,
"name": "West Springfield"
}
],
"account": {
"id": 22,
"companyName": "Sample Company",
"licenses": 99,
"countryCode": 1,
"companyAccountCode": null
},
"status": {
"message": "Leaving early on Tuesday (tomorrow).",
"timestamp": "2014-02-03T06:46:59+00:00"
}
}
],
"metadata": {
"page": 1,
"pagesCount": 1,
"recordsPerPage": 3,
"recordsCount": 2
}
}
Note the names of the users: Samuel and Rosamund.
Create a new user
We make a POST request to the /users endpoint. The format of the request body is very similar to the format of the GET response (and since we are accessing a collection endpoint, we must provide a collection of items we want to create):
POST /users HTTP/1.1
Host: api.geoop.com
Authorization: Bearer oJ_7Hj.f-F3f.kL
Content-Type: application/json
X-Version: 1.0
{
"users": [
{
"account": {
"id": 22
},
"firstName": "Geoff",
"lastName": "Wirtz",
"companyName": "Sample Company",
"phone": "+15559282001",
"mobile": "+15559332744",
"email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
"login": "gwirtz_sample",
"newPassword": "pa$$word",
"newPasswordConfirm": "pa$$word"
}
]
}
The response will contain a collection of created items (in our case there will be only one item in the collection).
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
X-Version: 1.0
{
"result": "success",
"users": [
{
"id": 114,
"firstName": "Geoff",
"lastName": "Wirtz",
"companyName": "Sample Company",
"email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
"phone": "+15559282001",
"mobile": "+15559332744",
"hourlyRate": 0,
"active": 1,
"deleted": false,
"colour": "#000000",
"isAssignable": false,
"role": {
"id": 2
},
"account": {
"id": 22
}
"status": {}
}
],
"metadata": {
"receivedItemsCount": 1,
"validItems": [
0
],
"invalidItems": []
}
}
Note that the POST request must always be made to a collection endpoint, because it is not possible to make POST requests to an existing item.
Create two more users
This time the body of the request will contain a collection with two items:
POST /users HTTP/1.1
Host: api.geoop.com
Authorization: Bearer oJ_7Hj.f-F3f.kL
Content-Type: application/json
X-Version: 1.0
{
"users": [
{
"account": {
"id": 22
},
"firstName": "Ivonne",
"lastName": "Becker",
"companyName": "Sample Company",
"phone": "+15559282001",
"mobile": "+15553135802",
"email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
"login": "ibecker_sample",
"newPassword": "pa$$word",
"newPasswordConfirm": "pa$$word"
},
{
"account": {
"id": 22
},
"firstName": "Eric",
"lastName": "Oliveira",
"companyName": "Sample Company",
"phone": "+15559282001",
"mobile": "+15554181228",
"email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
"login": "eoliveira_sample",
"newPassword": "pa$$word",
"newPasswordConfirm": "pa$$word"
}
]
}
The response will contain a collection of created items.
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
X-Version
{
"result": "success",
"users": [
{
"id": 115,
"firstName": "Ivonne",
"lastName": "Becker",
"companyName": "Sample Company",
"email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
"phone": "+15559282001",
"mobile": "+15553135802",
"hourlyRate": 0,
"active": 1,
"deleted": false,
"colour": "#000000",
"isAssignable": false,
"role": {
"id": 2
},
"account": {
"id: 22
},
"status": {}
},
{
"id": 116,
"firstName": "Eric",
"lastName": "Oliveira",
"companyName": "Sample Company",
"email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
"phone": "+15559282001",
"mobile": "+15554181228",
"hourlyRate": 0,
"active": 1,
"deleted": false,
"colour": "#000000",
"isAssignable": false,
"role": {
"id": 2
},
"account": {
"id": 22
},
"status": {}
}
],
"metadata": {
"receivedItemsCount": 2,
"validItems": [
0,
1
],
"invalidItems": []
}
}
Update user data
We make a PATCH request and for each item provide an id field so that the API can identify which item we want to update. All other item fields are optional and will be updated with the provided values.
PATCH /users HTTP/1.1
Host: api.geoop.com
Authorization: Bearer oJ_7Hj.f-F3f.kL
Content-Type: application/json
X-Version: 1.0
{
"users": [
{
"id": 115,
"mobile": "+15553135820"
},
{
"id": 116,
"status": {
"message": "Hello everyone!",
"timestamp": "2014-02-03T09:55:19+00:00"
}
}
]
}
The response object will contain a collection with the modified items.
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
X-Version: 1.0
{
"result": "success",
"users": [
{
"id": 115,
"firstName": "Ivonne",
"lastName": "Becker",
"companyName": "Sample Company",
"email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
"phone": "+15559282001",
"mobile": "+15553135820",
"hourlyRate": 0,
"active": 1,
"deleted": false,
"colour": "#000000",
"isAssignable": false,
"role": {
"id": 2
},
"account": {
"id": 22
},
"status": {}
},
{
"id": 116,
"firstName": "Eric",
"lastName": "Oliveira",
"companyName": "Sample Company",
"email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
"phone": "+15559282001",
"mobile": "+15554181228",
"hourlyRate": 0,
"active": 1,
"deleted": false,
"colour": "#000000",
"isAssignable": false,
"role": {
"id": 2
},
"account": {
"id": 22
},
"status": {
"message": "Hello everyone!",
"timestamp": "2014-02-03T09:55:19+00:00"
}
}
],
"metadata": {
"receivedItemsCount": 2,
"validItems": [
0,
1
],
"invalidItems": []
}
}
Note that the metadata object will always list both valid and invalid items, although in this case the invalidItems list is empty since all items have been processed successfully.
Mark users deleted
We make a POST request to the /users endpoint and set items' deleted property to true.
PATCH /users HTTP/1.1
Host: api.geoop.com
Authorization: Bearer oJ_7Hj.f-F3f.kL
Content-Type: application/json
X-Version: 1.0
{
"users": [
{
"id": 115,
"deleted": true
},
{
"id": 116,
"deleted": true
}
]
}
The response object will contain a collection with the modified items.
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
X-Version: 1.0
{
"result": "success",
"users": [
{
"id": 115,
"firstName": "Ivonne",
"lastName": "Becker",
"companyName": "Sample Company",
"email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
"phone": "+15559282001",
"mobile": "+15553135820",
"hourlyRate": 0,
"active": 0,
"deleted": true,
"colour": "#000000",
"isAssignable": false,
"role": {
"id": 2
},
"account": {
"id": 22
},
"status": {}
},
{
"id": 116,
"firstName": "Eric",
"lastName": "Oliveira",
"companyName": "Sample Company",
"email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
"phone": "+15559282001",
"mobile": "+15554181228",
"hourlyRate": 0,
"active": 0,
"deleted": true,
"colour": "#000000",
"isAssignable": false,
"role": {
"id": 2
},
"account": {
"id": 22
},
"status": {
"message": "Hello everyone!",
"timestamp": "2014-02-03T09:55:19+00:00"
}
}
],
"metadata": {
"receivedItemsCount": 2,
"validItems": [
0,
1
],
"invalidItems": []
}
}
Physically delete users Not Implemented
We make a DELETE request to the /users endpoint and specify which items have to be deleted.
DELETE /users HTTP/1.1
Host: api.geoop.com
Authorization: Bearer oJ_7Hj.f-F3f.kL
Content-Type: application/json
X-Version: 1.0
{
"users": [
{
"id": 115
},
{
"id": 116
}
]
}
The response object will contain a collection with the basic information about deleted items.
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
X-Version: 1.0
{
"result": "success",
"users": [
{
"id": 115
}
{
"id": 116
}
],
"metadata": {
"receivedItemsCount": 2,
"validItems": [
0,
1
],
"invalidItems": []
}
}
Understanding validation errors
If some or all items in the request object contain invalid data, the API Server will not process such items and will mark them failed. If that is the case, the value of the result property of the response object will be failure. No items from the request (even valid ones) will be saved.
Let's try to add two more users without specifying the name and mobile number of the second user. We make the following POST request to the /users endpoint:
POST /users HTTP/1.1
Host: api.geoop.com
Authorization: Bearer oJ_7Hj.f-F3f.kL
Content-Type: application/json
X-Version: 1.0
{
"users": [
{
"account": {
"id": 22
},
"firstName": "Elijah",
"lastName": "Burt",
"companyName": "Sample Company",
"phone": "+15559282001",
"mobile": "+15554576422",
"email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
"login": "eburt_sample",
"newPassword": "pa$$word",
"newPasswordConfirm": "pa$$word"
},
{
"account": {
"id": 22
},
"companyName": "Sample Company",
"phone": "+15559282001",
"email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
"login": "sample",
"newPassword": "pa$$word",
"newPasswordConfirm": "pa$$word"
}
]
}
The response object will contain a failures collection with an item that has not passed validation. The latter will contain a rawData object representing the incoming data as the API Server understood it and a nested collection of error objects that help understand what exactly caused the item failure.
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
X-Version: 1.0
{
"result": "failure",
"failures": [
{
"rawData": {
"account": {
"id": 22
},
"companyName": "Sample Company",
"phone": "+15559282001",
"email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
"login": "sample",
"newPassword": "pa$$word",
"newPasswordConfirm": "pa$$word"
},
"errors": [
{
"type": "validation",
"code": 1040,
"message": "Required field 'firstName' was not found in the item.",
"field": "firstName"
},
{
"type": "validation",
"code": 1040,
"message": "Required field 'lastName' was not found in the item.",
"field": "lastName"
},
{
"type": "validation",
"code": 1040,
"message": "Required field 'mobile' was not found in the item.",
"field": "mobile"
}
]
}
],
"metadata": {
"receivedItemsCount": 2,
"validItems": [
0
],
"invalidItems": [
1
]
}
}
Note that the index of the failed item in the response collection can be found in the invalidItems property of the metadata object.
Understanding fatal errors
Fatal errors occur when the request object is malformed or if the API Server triggers a severe unrecoverable error that prevents the process flow from successful continuation.
Let's try to update a user's mobile number via the /jobs endpoint by making the following PATCH request:
PATCH /jobs HTTP/1.1
Host: api.geoop.com
Authorization: Bearer oJ_7Hj.f-F3f.kL
Content-Type: application/json
X-Version: 1.0
{
"users": [
{
"id": 117,
"mobile": "+15554576423"
}
]
}
The value of the result property of the response object will now be error meaning that the request cannot be processed by the API Server. The response will also contain an error object with additional information about the caused error.
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
X-Version: 1.0
{
"result": "error",
"error": {
"type": "content",
"code": 1247,
"message": "Collection of type 'users' is not supported by this endpoint."
}
}
Note the HTTP status code of the response object: 422 Unprocessable Entity. It indicates that although the syntax of the request was valid and the API Server understood it, it still was not able to process this request due to it having invalid content.