Paginated Lists in API Responses
Introduction
This documentation explains the structure of JSON-LD API responses, focusing on the use of PaginatedList objects for properties that reference a list of related objects.
PaginatedList Object
A PaginatedList object is used to represent properties that have one-to-many or many-to-many relationships. Instead of embedding an array of related objects directly in the response, a PaginatedList provides a link (@id) to the endpoint where the list can be retrieved. This method is particularly useful when dealing with large datasets, as it allows for pagination for efficient data retrieval and improved performance.
Important Note:
A PaginatedList object will not be utilized when there is not an available API endpoint to retrieve the list of objects, instead, the full list will be included in the response. An example of this caveat is a list of
licensesattached to licensed content
Structure of PaginatedList
A PaginatedList object includes the following properties:
@type: Indicates the type of the list, which is always "PaginatedList".@id: The URL to the endpoint where the full list can be accessed.itemType: The type of items including within the list.total: The total number of items in the list.
Example JSON-LD API Response
Below is an example of a JSON-LD API response that utilizes PaginatedList objects for properties with one-to-many or many-to-many relationships:
{
"@context": "https://grcschema.org/",
"@type": "Account",
"elementId": 1,
"displayName": null,
"domain": "unifiedcompliance.com",
"groups": {
"@type": "PaginatedList",
"@id": "https://api.app.unifiedcompliance.com/api/my-account/group",
"itemType": "Group",
"total": 7
},
"handle": "Test",
"initiatives": {
"@type": "PaginatedList",
"@id": "https://api.app.unifiedcompliance.com/api/my-account/initiative",
"itemType": "Initiative",
"total": 2
},
"name": "Test Account One",
"accountMemberships": {
"@type": "PaginatedList",
"@id": "https://api.app.unifiedcompliance.com/api/my-account/membership",
"itemType": "AccountMembership",
"total": 12
},
"organization": {
"@context": "https://grcschema.org/",
"@type": "Organization",
"@id": "https://api.app.unifiedcompliance.com/api/organization/5005",
"elementId": 5005,
"description": "By applying the scientific method to compliance -- rigorously testing best practices and methodologies as well as analyzing and organizing information into a rational format -- Network Frontiers has developed a logical approach to IT compliance that re...",
"domain": "unifiedcompliance.com",
"domains": {
"@type": "PaginatedList",
"@id": "https://api.app.unifiedcompliance.com/api/organization/5005/domain",
"itemType": "Domain",
"total": 7
},
"email": "info@unifiedcompliance.com",
"emails": {
"@type": "PaginatedList",
"@id": "https://api.app.unifiedcompliance.com/api/organization/5005/email",
"itemType": "Email",
"total": 7
},
"founded": 1992,
"legalName": "Unified Compliance",
"name": "Unified Compliance",
"names": {
"@type": "PaginatedList",
"@id": "https://api.app.unifiedcompliance.com/api/organization/5005/name",
"itemType": "Name",
"total": 1
},
"parent": null,
"parentId": null,
"phoneNumber": "+1 866-924-3791",
"phoneNumbers": {
"@type": "PaginatedList",
"@id": "https://api.app.unifiedcompliance.com/api/organization/5005/phone-number",
"itemType": "PhoneNumber",
"total": 2
},
"postalAddress": {
"@type": "PostalAddress",
"elementId": 3149,
"address1": "Las Vegas Boulevard South 23",
"address2": "",
"city": "Las Vegas",
"country": "United States of America",
"countryCode": "USA",
"postalCode": "89109",
"primary": true,
"stateTerritoryProvince": "Nevada"
},
"postalAddresses": {
"@type": "PaginatedList",
"@id": "https://api.app.unifiedcompliance.com/api/organization/5005/postal-address",
"itemType": "PostalAddress",
"total": 7
},
"roles": [],
"socialAddresses": {
"@type": "PaginatedList",
"@id": "https://api.app.unifiedcompliance.com/api/organization/5005/social-address",
"itemType": "SocialAddress",
"total": 7
},
"tags": {
"@type": "PaginatedList",
"@id": "https://api.app.unifiedcompliance.com/api/organization/5005/tag",
"itemType": "Tag",
"total": 11
},
"ultimateParentId": null,
"coreMetaData": {
"@type": "CoreMetaData",
"created": {
"@type": "Created",
"timeStamp": "2022-09-08T20:10:52.000000Z",
"organization": null,
"person": {
"@type": "Person",
"@id": "https://api.app.unifiedcompliance.com/api/person/1",
"elementId": 1,
"name": "System System"
}
},
"liveStatus": true,
"modified": {
"@type": "Modified",
"timeStamp": "2023-04-04T18:02:27.000000Z",
"organization": null,
"person": {
"@type": "Person",
"@id": "https://api.app.unifiedcompliance.com/api/person/1",
"elementId": 1,
"name": "System System"
}
},
"notes": null,
"status": null,
"supersededBy": null,
"validated": false,
"checksum": "6ba4d7c11f3faefb8b2eb8d3a6c0058c5a4ee31d959713cba308b3551ff549af"
}
},
"coreMetaData": {
"@type": "CoreMetaData",
"created": {
"@type": "Created",
"timeStamp": "2023-03-02T15:26:44.000000Z",
"organization": null,
"person": {
"@type": "Person",
"@id": "https://api.app.unifiedcompliance.com/api/person/1",
"elementId": 1,
"name": "Test Person"
}
},
"liveStatus": true,
"modified": {
"@type": "Modified",
"timeStamp": "2024-04-29T19:51:10.000000Z",
"organization": null,
"person": {
"@type": "Person",
"@id": "https://api.app.unifiedcompliance.com/api/person/1",
"elementId": 1,
"name": "Test Person"
}
},
"notes": null,
"status": null,
"supersededBy": null,
"validated": true,
"checksum": "6ba4d7c11f3faefb8b2eb8d3a6c0058c5a4ee31d959713cba308b3551ff549af"
}
}
In this example, properties such as groups, initiatives, and accountMemberships are represented as PaginatedList objects, each with a link to the endpoint where the full list of related items can be retrieved.