In a previous post, we discussed Authentication and Http Verb usage in the REST API. In today's post, we'll discuss request patterns.
We'll look at patterns and examples for the following requests :
- Retrieve a single item
- Retrieve a list of items
- Create an item
- Update an item
- Delete an item
Retrieving a single item
To retrieve a single entity, a client would perform a GET request for that entity's URI, optionally specifying the format to return the entity in.
Request:
GET https://.../data/contact/123 Accept: application/json
Response:
Content-Type: application/json
{
"type": "Contact",
"id": "123",
"firstName": "Joe",
"lastName": "Smith",
...
}
Retrieve a list of items
To retrieve a list of entities, a client would perform a GET request for that entity type's URI, specifying the query parameters to use to filter the list, and optionally specifying the format to return the entities in.
Request:
GET https://.../data/contacts?search=a*&count=5 Accept: application/json
Response:
Content-Type: application/json
{
"elements": [
{
"type": "Contact",
"id": "515",
"createdAt": "1239744629",
"depth": "minimal",
...
},
{
"type": "Contact",
"id": "516",
"createdAt": "1239806222",
"depth": "minimal",
...
},
...
],
"page": 1,
"pageSize": 5,
"total": 2566
}
Note that the URI is the plural form of the URI of a single entity of that type. The pageSize indicates the number requested on this page, and the total indicates the total number of matches in the system.
Create an item
To create an entity, a client would perform a POST request to that entity's URI, specifying the format the entity is being supplied in, and optionally specifying the format to return the newly-persisted entity in.
Request:
POST https://.../data/contact/
Content-Type: application/json
Accept: application/json
{
"type": "Contact",
"firstName": "Joe",
"lastName": "Smith",
...
}
Response:
Content-Type: application/json
{
"type": "Contact",
"id": "123",
"firstName": "Joe",
"lastName": "Smith",
...
}
Update an item
To update an entity, a client would perform a PUT request to that entity's URI, specifying the format the entity is being supplied in, and optionally specifying the format to return the newly-updated entity in.
Request:
PUT https://.../data/contact/123
Content-Type: application/json
Accept: application/json
{
"type": "Contact",
"id": "123",
"firstName": "Joe",
"lastName": "Smith",
...
}
Response:
Content-Type: application/json
{
"type": "Contact",
"id": "123",
"firstName": "Joe",
"lastName": "Smith",
...
}
Delete an item
To delete an entity, a client would perform a DELETE request to that entity's URI.
Request:
DELETE https://.../data/contact/123
We hope that you find this helpful.
Thanks,
Fred
Comments