As a starting point for a suggested way to improve the partial fetching options and searching we could consider the following options.

Partial selection of template and agreement nested resources

If there nested resources (e.g., metadata, clauses, agreement data), represent them in a hierarchy beneath the primary resource ID

• /templates/{templateId}/metadata
• /templates/{templateId}/clauses/{clauseId}
• /templates/{templateId}/model
• /agreements/{agreementId}/metadata
• /agreements/{agreementId}/data

The paths above should consider versioning of the templates and agreement too so potentially adding:

• /version/{versionId} (where versionId is a valid version)

A possible extension could be retrieval could be:

• GET /agreements/{agreementId}?fields=id&keywords=foo,bar

Pagination

Common query parameters for pagination are:

1. Offset/Limit:

• GET /templates?offset=0&limit=10
• offset and limit provide straightforward pagination.

2. Page/Size:

• GET /templates?page=1&pageSize=10
• More user-friendly at the expense of slightly less control.

Include pagination metadata in responses:

• Return pagination details in response headers or as part of a top-level response object. This might include:
• X-Total-Count: Total number of resources available.
• X-Total-Pages: Number of pages (if using page-based pagination).
  Alternatively, include a pagination object in the JSON response:

{
  "data": [...],
  "meta": {
    "total": 100,
    "offset": 0,
    "limit": 10
  }
}

Pagination links

Consider returning next, prev, first, and last links in the response body. This makes it easier for clients to navigate collections:

{
  "data": [...],
  "links": {
    "self": "/templates?offset=0&limit=10",
    "next": "/templates?offset=10&limit=10",
    "prev": null,
    "first": "/templates?offset=0&limit=10",
    "last": "/templates?offset=90&limit=10"
  },
  "meta": {
    "total": 100,
    "offset": 0,
    "limit": 10
  }
}

Hi @niallroche

I sent a pr that successfully resolves this issue.