Filtering and pagination

The largest level of granularity for your documents is tied to the country and the document type. For example, if you want to retrieve all the documents you have sent for preservation for the registro-volontari document type in Italy, you can send a GET request to /preserved-documents/it/registro-volontari.

Filtering the results

If you want you can filter the returned collection by status and/or creation date.

Filtering by status

To limit the returned values to a specific status, you can add the status query parameter to the request.

For example, if you want to retrieve all the documents that haven't completed the perservation process yet, you can send a GET request to /preserved-documents/it/registro-volontari?status=to_be_stored.

All the possible values for the status parameter are:

  • to_be_stored - the document has been created but not yet sent for preservation
  • sent - the document has been sent for preservation
  • sent_metadata - the document metadata has been sent to the preservation provider
  • stored - the document has been preserved

Filtering by creation date

You can also filter the results by creation date. To do so, you can add the created_at query parameter to the request.

To add specific constraints to the created_at parameter, you can use the following operators:

  • before : limit the result to documents created before the specified date
  • strictly_before : limit the result to documents created before the specified date (excluding the specified date)
  • after : limit the result to documents created after the specified date
  • strictly_after : limit the result to documents created after the specified date (excluding the specified date)

For example, if you want to retrieve all the documents of a given type created during January 2023, you can send a GET request to /preserved-documents/it/registro-volontari?created_at[after]=2023-01-01&created_at[strictly_before]=2023-02-01.

Pagination

All the endpoints that return a collection of items are paginated. By default, the pagination is set to 30 items per page, but you can change this value up to 100 by adding the itemsPerPage query parameter to the request.

To get full information about the pagination you can send the HTTP header application/ld+json. You will receive an enriched payload that encapsulates the original result adding these keys:

  • hydra:member - the array with the retrieved items
  • hydra:totalItems - total filtered items
  • hydra:view
    • hydra:first - URL to the first page
    • hydra:last - URL to the last page
    • hydra:next - URL to the next page
  • hydra:search - object containing information about the filters

Customizing the pagination

You can adapt the pagination to your needs by adding the following query parameters to the request:

  • page=n indicates the page number you want to get
  • itemsPerPage=m number of items per page (hard limited to 100)

For example GET /preserved-documents/it/registro-volontari?page=1&itemsPerPage=1 will return something like:

Copy
Copied
  {
    "@context": "/contexts/RegistroVolontari",
    "@id": "/preserved-documents/it/registro-volontari",
    "@type": "hydra:Collection",
    "hydra:totalItems": 22,
    "hydra:member": [
      {
        "uuid": "655d45ab-d961-432c-9d3f-7dcdbccca7b5",
        "created_at": "2023-05-02T02:00:00",
        "updated_at": "2023-05-02T02:00:00",
        "preserved_object_id": "59030240-709a-448b-b1bd-b62cdf8bbe80",
        "status": "stored",
        "status_history": { "stored": "2023-05-02T02:00:00" },
        "error_message": null
      }
    ],
    "hydra:view": {
      "@id": "/preserved-documents/it/registro-volontari?itemsPerPage=1&page=1",
      "@type": "hydra:PartialCollectionView",
      "hydra:first": "/preserved-documents/it/registro-volontari?itemsPerPage=1&page=1",
      "hydra:last": "/preserved-documents/it/registro-volontari?itemsPerPage=1&page=2",
      "hydra:next": "/preserved-documents/it/registro-volontari?itemsPerPage=1&page=2"
    },
    "hydra:search": {
      "@type": "string",
      "hydra:template": "string",
      "hydra:variableRepresentation": "string",
      "hydra:mapping": [
        {
          "@type": "string",
          "variable": "string",
          "property": "string",
          "required": true
        }
      ]
    }
  }

See Hydra specifications for more information.