Skip to content

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.

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

Binary stream

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 a file to an API model object Recommended for
Embedded bytes Sum of all embedded Base64 encoded bytes should be less than 1 megabyte per request 1 Low resolution profile photos
Separate upload requests None 2 Any type of file

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.

Info

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.

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

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

Register temporary file 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.

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

Content-Type: image/jpeg

{
  "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.

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

{
  "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"
        }
      }
    }
  ]
}

{
  "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 upload 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.

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

{
  "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.

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

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

{
  "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"
        }
      }
    }
  ]
}