How Can We Help?

Pure API: Working with filesPure API: Working with files

Parts of the Pure API model use files to store information, such as a ClassifiedFile used to store a profile photo of a Person or an ElectronicVersionFile used to store an electronic version of a BookAnthology. ClassifiedFile, ElectronicVersionFile and other types that reference a file stored in Pure are collectively known as 'file referencing types'. An instance of such a type is known as a 'file referencing object' - an object that references a file stored in Pure, such as the profile photo metadata of a JPEG image stored in Pure.

You can download the file of an existing file referencing object and you can associate file data with a new file referencing object. You cannot replace the file associated with a file referencing object; you must first remove the file referencing object and add a new one.

Downloading files

You can download files using the /files sub-resource of an API content object, further qualified with the fileId value of a file referencing object, such as fileId of a ClassifiedFile in the case of profile photos on persons. A request for /persons/<some person UUID>/files/<some ClassifiedFile.fileId profile photo value> will stream the profile photo image of a person.

File download requests (also) require use of API key

All requests to the Pure API must include an API key, including when your client downloads a file from the Pure API. If your client attempts to download a file without specifying an api-key header then the request will fail with 401 “Request not authorized”. By extension, if you manually copy a file URL from a Pure API response and navigate to it using your browser then that request will fail, too, as your browser will not automatically include the required api-key header.

If you need to serve a file from the Pure API, such as to a browser-based guest, ensure that API keys are not made available client-side. That can be achieved in several ways, such as by:

copying relevant files to another store beforehand and serving from there, removing the need for using an API key at the time of serving
introducing something in front of the Pure API that handles caching and makes server-side requests to the Pure API using a server-side-only API key

Click here for sample request

Request URL:

https://{your Pure hostname}/ws/api/persons/29492640-5030-4843-91c1-7d85ca997749/files/MDY2MDdh

Response body: A binary image

Uploading files

You can associate file data with a file referencing object in two ways:

By first uploading a file to register a temporary file and then using that temporary file on a file referencing object.
By embedding bytes of a file directly on a file referencing object.

The following table lists pros and cons of the ways you can upload files to the Pure API:

Upload type	Recommended maximum file size	Number of requests required to add N files to a API model object	Recommended for
Separate upload requests	None	`N+1`	Any type of file
Embedded bytes	Sum of all embedded bytes should be less than 1 megabyte per request	1	Low resolution profile photos

You only need to upload a file once; when it has been associated with a file referencing object the file will stay associated until the file referencing object is removed or the object, that the file referencing object is associated with, is deleted.

It is not possible to upload files via the API by providing a URL from which the file can be downloaded.

A file referencing object requires a small subset of its metadata to be specified in addition to the file data: A filename specified for fileName, a MIME type specified for mimeType, and a file size specified for size.

Separate upload requests

Using separate upload requests is useful when you need to associate file data of arbitrary size.

Uploading a file using a separate upload request is a four step process:

Fetch existing Pure API model object to manipulate file referencing objects of.

Click here for sample request

Request

https://{your Pure hostname}/ws/api/persons/29492640-5030-4843-91c1-7d85ca997749

Response body:

{
          "pureId": 417899,
          "uuid": "29492640-5030-4843-91c1-7d85ca997749",
          ...
          "name": {
            "firstName": "Some-first-name",
            "lastName": "Some-last-name"
          },
          ...
        }

Repeatedly register temporary files by uploading the files using /file-uploads of the endpoint you will later be using the file for, such as /persons/file-uploads in case of a profile photo on a Person. An UploadedFile is returned from each upload request.

Click here for sample request

Request URL:

https://{your Pure hostname}/ws/api/persons/file-uploads

Headers:

Content-Type: image/jpeg
        ...

Request body:

<Binary data>

Response body:

{
          "digest": "c61df35de3ad4168ef85a2ff30bb5f096eb913cd",
          "digestType": "SHA-1",
          "size": 16956,
          "mimeType": "image/jpeg",
          "timeStamp": "2022-03-23T07:11:24.751181Z",
          "expires": "2022-03-23T09:11:24.751197Z",
          "key": "0a4f5fa4-5cf3-40b0-ad06-77471544350e"
        }

Modify file referencing objects to each use a UploadedFile objects previously returned from each upload request. Such as by setting a UploadedFile as uploadedFile on the ClassifiedFile object that represents information about a specific profile photo of the currently handled Person.

Submit the created/updated Pure API model object to the relevant endpoint, such as /persons.

Click here for sample request

Request URL:

https://{your Pure hostname}/ws/api/persons/29492640-5030-4843-91c1-7d85ca997749

Request body:

{
          "pureId": 417899,
          "uuid": "29492640-5030-4843-91c1-7d85ca997749",
          ...
          "profilePhotos": [
            {
              "uploadedFile": {
                "digest": "c61df35de3ad4168ef85a2ff30bb5f096eb913cd",
                "digestType": "SHA-1",
                "size": 16956,
                "mimeType": "image/jpeg",
                "timeStamp": "2022-03-23T07:11:24.751181Z",
                "expires": "2022-03-23T09:11:24.751197Z",
                "key": "0a4f5fa4-5cf3-40b0-ad06-77471544350e"
              },
              "fileName": "small_image_added.jpeg",
              "mimeType": "image/jpeg",
              "size": 12551,
              "type": {
                "uri": "/dk/atira/pure/person/personfiles/portrait",
                "term": {
                  "en_GB": "Portrait",
                  "es_ES": "Retrato",
                  "fr_FR": "portrait",
                  "de_DE": "Portrait"
                }
              }
            }
          ],
          ...
        }

Response body:

{
          "pureId": 417899,
          "uuid": "29492640-5030-4843-91c1-7d85ca997749",
          ...
          "profilePhotos": [
            {
              "pureId": 417914,
              "fileId": "MDY2MDdh",
              "fileName": "small_image_added.jpeg",
              "mimeType": "image/jpeg",
              "size": 12551,
              "url": "https://pure-api-test.devel.elsevierpure.com/ws/api/persons/29492640-5030-4843-91c1-7d85ca997749/files/MDY2MDdh/small_image_added.jpeg",
              "type": {
                "uri": "/dk/atira/pure/person/personfiles/portrait",
                "term": {
                  "en_GB": "Portrait",
                  "es_ES": "Retrato",
                  "fr_FR": "portrait",
                  "de_DE": "Portrait"
                }
              }
            }
          ],
          ...
        }

UploadedFile objects have a number of limitations:

A temporary file registered using /file-uploads is short-lived; you can use an UploadedFile for up to two hours.
You can only use an UploadedFile object on a single file referencing object. If you need to use a specific file on multiple file referencing objects then you must uploaded the file for each intended use.

Embedded bytes

Embedding bytes directly on a file associating object is useful in situations where you need to associate a small file. A single request is needed to submit file data for multiple file referencing objects on a Pure API model object.

Uploading a file using a embedded bytes is a three step process:

(Fetch existing Pure API model object to manipulate file referencing objects of.)

Click here for sample request

Request URL:

https://{your Pure hostname}/ws/api/persons/29492640-5030-4843-91c1-7d85ca997749

Response body:

{
          "pureId": 417899,
          "uuid": "29492640-5030-4843-91c1-7d85ca997749",
          ...
          "name": {
            "firstName": "Some-first-name",
            "lastName": "Some-last-name"
          },
          ...
        }

Modify file referencing objects to have relevant base64-encoded file data set in the fileData field, such as by setting fileData on the ClassifiedFile object that represents information about a specific profile photo of the currently handled Person.

Submit the created/updated Pure API model object to the relevant endpoint, such as /persons.

Click here for sample request

Request URL:

https://{your Pure hostname}/ws/api/persons/29492640-5030-4843-91c1-7d85ca997749

Request body:

{
          "pureId": 417899,
          "uuid": "29492640-5030-4843-91c1-7d85ca997749",
          ...
          "profilePhotos": [
            {
              "fileData": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMCAgMCAgMDAwMEAwMEBQgFBQQEBQoHBwYIDAoMDAsK
              CwsNDhIQDQ4RDgsLEBYQERMUFRUVDA8XGBYUGBIUFRT/2wBDAQMEBAUEBQkFBQkUDQsNFBQUFBQU
              ...",
              "fileName": "small_image_added.jpeg",
              "mimeType": "image/jpeg",
              "size": 12551,
              "type": {
                "uri": "/dk/atira/pure/person/personfiles/portrait",
                "term": {
                  "en_GB": "Portrait",
                  "es_ES": "Retrato",
                  "fr_FR": "portrait",
                  "de_DE": "Portrait"
                }
              }
            }
          ],
          ...
        }

Response body:

{
          "pureId": 417899,
          "uuid": "29492640-5030-4843-91c1-7d85ca997749",
          ...
          "profilePhotos": [
            {
              "pureId": 417919,
              "fileId": "MDY2MDdm",
              "fileName": "small_image_added.jpeg",
              "mimeType": "image/jpeg",
              "size": 12551,
              "url": "https://pure-api-test.devel.elsevierpure.com/ws/api/persons/29492640-5030-4843-91c1-7d85ca997749/files/MDY2MDdh/small_image_added.jpeg",
              "type": {
                "uri": "/dk/atira/pure/person/personfiles/portrait",
                "term": {
                  "en_GB": "Portrait",
                  "es_ES": "Retrato",
                  "fr_FR": "portrait",
                  "de_DE": "Portrait"
                }
              }
            }
          ],
          ...
        }

Published at April 29, 2025

How Can We Help?

Search Results

Filter By Category

Contact Us

Pure API: Working with filesPure API: Working with files

Downloading files

File download requests (also) require use of API key

Click here for sample request

Uploading files

Separate upload requests

Click here for sample request

Click here for sample request

Click here for sample request

Embedded bytes

Click here for sample request

Click here for sample request