How Can We Help?

FilesFiles

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.

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.

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"
        }
      }
    }
  ],
  ...
}

Updated at September 06, 2024

How Can We Help?

Search Results

Filter By Category

Contact Us

FilesFiles

Downloading files

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