Understanding the Activity API data model

There are a few typical API operations that you would usually want to implement. These operations include the following:
  • Retrieving a collection of resources
  • Retrieving a single resource
  • Creating a new resource
  • Updating a resource
The example Activities API provides an example of the types of HTTP operations and endpoints that you would most likely want to create.
API functionality HTTP operation and endpoint
Retrieve a list of activities GET /activities
Retrieve a single activity GET /activities/{activityId}
Create a new activity POST /activities
Update an activity PATCH /activities/{activityId}

You design the inputs and outputs to the Activities API operations in JSON schema files.

Example GET /activities response

The following code sample illustrates what a possible JSON response to a GET /activities operation could look like. Understanding what you want the output to look like helps you determine how to structure the JSON schema file.
[ 
  "assignedUser": {
    "displayName": "Alice Applegate",
    "publicId": "pc:305",
    "username": "aapplegate"
  },
  "escalated": false,
  "escalationDate": "2018-04-23T16:22:23.976Z",
  "mandatory": true,
  "priority": "high",
  "publicId": "pc:203",
  "status": "open",
  "subject": "Action Required",
  "targetDate": "2018-04-23T16:22:23.976Z"
]

Example GET /activities/{activityId} response

The following code sample illustrates what a possible JSON response to a GET /activities/{activityId} operation for activity pc:203 could look like. Understanding what you want the output to look like helps you determine how to structure the JSON schema file.
{
  "assignedUser": {
    "displayName": "Alice Applegate",
    "publicId": "pc:305",
    "username": "aapplegate"
  },
  "description": "...",
  "mandatory": false,
  "priority": "normal",
  "publicId": "pc:101",
  "relatedAccount": {
    "accountNumber": "C000212105",
    "displayName": "C000212105",
    "publicId": "pc:ds:1"
  },
  "relatedJob": {
    "displayName": "SUB00000002",
    "jobNumber": "SUB00000002",
    "jobType": "Submission",
    "publicId": "pc:11"
  },
  "relatedPolicy": {
    "displayName": "pc:6",
    "publicId": "pc:6"
  },
  "relatedPolicyPeriod": {
    "displayName": "6996053459, 01/18/2017, 01/18/2018, SUB00000002",
    "policyNumber": "6996053459",
    "publicId": "pc:11"
  },
  "status": "open",
  "subject": "New subject 2",
  "targetDate": "2018-04-18T23:05:53.981Z"
}