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