Files

Files are attachment resources rooted in the /v1/files/{org_label}/{project_label}/ collection.

Each file…

  • belongs to a project identifier by the label {project_label}
  • inside an organization identifier by the label {org_label}

Access to resources in the system depends on the access control list set for them. Depending on the access control list, a caller may need to prove its identity by means of an access token passed to the Authorization header (Authorization: Bearer {token}). Please visit Authentication to learn more about how to retrieve an access token.

Authorization notes

When modifying files, the caller must have the permissions defined on the storage associated to the file on the current path of the project or the ancestor paths.

When reading files, the caller must have the permissions defined on the storage associated to the file on the current path of the project or the ancestor paths.

Create a file using POST

POST /v1/files/{org_label}/{project_label}

The json payload:

  • If the @id value is found on the payload, this @id will be used.
  • If the @id value is not found on the payload, an @id will be generated as follows: base:{UUID}. The base is the prefix defined on the resource’s project ({project_label}).

Example

Request
curl -XPOST -F "file=@/path/to/myfile.jpg;type=image/jpeg" "https://nexus.example.com/v1/files/myorg/myproj"
Full source at GitHub
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9",
  "@type": "File",
  "_bytes": 670,
  "_digest": {
    "_algorithm": "SHA-256",
    "_value": "25fc54fba0beec17a598b5a68420ded1595b2f76f0a0b7c6077792ece828bc2e"
  },
  "_filename": "myfile.jpg",
  "_mediaType": "image/jpeg",
  "_incoming": "https://nexus.example.com/v1/files/myorg/myproj/base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9/incoming",
  "_outgoing": "https://nexus.example.com/v1/files/myorg/myproj/base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9/outgoing",
  "_self": "https://nexus.example.com/v1/files/myorg/myproj/base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/file.json",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 1,
  "_deprecated": false,
  "_createdAt": "2019-01-28T12:15:33.238Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-01-28T12:15:33.238Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub

Create a file using PUT

This alternative endpoint to create a resource is useful in case the json payload does not contain an @id but you want to specify one. The @id will be specified in the last segment of the endpoint URI.

PUT /v1/files/{org_label}/{project_label}/{file_id}

Note that if the payload contains an @id different from the {file_id}, the request will fail.

Example

Request
curl -XPUT -F "file=@/path/to/myfile.jpg;type=image/jpeg" "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile.jpg"
Full source at GitHub
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "nxv:myfile",
  "@type": "File",
  "_bytes": 670,
  "_digest": {
    "_algorithm": "SHA-256",
    "_value": "25fc54fba0beec17a598b5a68420ded1595b2f76f0a0b7c6077792ece828bc2e"
  },
  "_filename": "myfile.jpg",
  "_mediaType": "image/jpeg",
  "_incoming": "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile/incoming",
  "_outgoing": "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile/outgoing",
  "_self": "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/file.json",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 1,
  "_deprecated": false,
  "_createdAt": "2019-01-28T12:15:33.238Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-01-28T12:15:33.238Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub

Create a file (specific storage)

POST /v1/files/{org_label}/{project_label}?storage={storageId}

Or

PUT /v1/files/{org_label}/{project_label}/{file_id}?storage={storageId}

… where {storageId} selects a specific storage backend where the file will be uploaded.

Example

Request
curl -XPOST -F "file=@/path/to/myfile.jpg;type=image/jpeg" "https://nexus.example.com/v1/files/myorg/myproj?storage=nxv:mys3storage"
Full source at GitHub
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9",
  "@type": "File",
  "_bytes": 670,
  "_digest": {
    "_algorithm": "SHA-256",
    "_value": "25fc54fba0beec17a598b5a68420ded1595b2f76f0a0b7c6077792ece828bc2e"
  },
  "_filename": "myfile.jpg",
  "_mediaType": "image/jpeg",
  "_incoming": "https://nexus.example.com/v1/files/myorg/myproj/base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9/incoming",
  "_outgoing": "https://nexus.example.com/v1/files/myorg/myproj/base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9/outgoing",
  "_self": "https://nexus.example.com/v1/files/myorg/myproj/base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/file.json",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 1,
  "_deprecated": false,
  "_createdAt": "2019-01-28T12:15:33.238Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-01-28T12:15:33.238Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub

Link an existing file using POST

Creates a resource from an existing file, provided that the storage backend where it is located supports the operation.

POST /v1/files/{org_label}/{project_label}?storage={storageId}
  {
    "filename": "myfile.png",
    "path": "relative/path/to/myfile.png",
    "mediaType": "image/png"
  }

… where {storageId} selects a specific storage backend that supports linking existing files.

Example

Request
curl -XPOST "https://nexus.example.com/v1/files/myorg/myproj?storage=nxv:mys3storage" -d \
'{
    "filename": "myfile.png",
    "path": "relative/path/to/myfile.png",
    "mediaType": "image/png"
}'
Full source at GitHub
Payload
{
    "filename": "myfile.png",
    "path": "relative/path/to/myfile.png",
    "mediaType": "image/png"
}
Full source at GitHub
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9",
  "@type": "File",
  "_bytes": 670,
  "_digest": {
    "_algorithm": "SHA-256",
    "_value": "25fc54fba0beec17a598b5a68420ded1595b2f76f0a0b7c6077792ece828bc2e"
  },
  "_filename": "myfile.png",
  "_location": "https://s3.us-west-1.amazonaws.com/mybucket/relative/path/to/myfile.png",
  "_mediaType": "image/png",
  "_incoming": "https://nexus.example.com/v1/files/myorg/myproj/base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9/incoming",
  "_outgoing": "https://nexus.example.com/v1/files/myorg/myproj/base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9/outgoing",
  "_self": "https://nexus.example.com/v1/files/myorg/myproj/base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/file.json",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 1,
  "_deprecated": false,
  "_createdAt": "2019-01-28T12:15:33.238Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-01-28T12:15:33.238Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub

Link an existing file using PUT

Creates a resource from an existing file, provided that the storage backend where it is located supports the operation.

This alternative endpoint allows to specify the resource @id.

PUT /v1/files/{org_label}/{project_label}/{file_id}?storage={storageId}
  {
    "filename": "myfile.png",
    "path": "relative/path/to/myfile.png",
    "mediaType": "image/png"
  }

… where {storageId} selects a specific storage backend that supports linking existing files.

Example

Request
curl -XPUT "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile.png?storage=nxv:mys3storage" -d \
'{
    "filename": "myfile.png",
    "path": "relative/path/to/myfile.png",
    "mediaType": "image/png"
}'
Full source at GitHub
Payload
{
    "filename": "myfile.png",
    "path": "relative/path/to/myfile.png",
    "mediaType": "image/png"
}
Full source at GitHub
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9",
  "@type": "File",
  "_bytes": 670,
  "_digest": {
    "_algorithm": "SHA-256",
    "_value": "25fc54fba0beec17a598b5a68420ded1595b2f76f0a0b7c6077792ece828bc2e"
  },
  "_filename": "myfile.png",
  "_location": "https://s3.us-west-1.amazonaws.com/mybucket/relative/path/to/myfile.png",
  "_mediaType": "image/png",
  "_incoming": "https://nexus.example.com/v1/files/myorg/myproj/base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9/incoming",
  "_outgoing": "https://nexus.example.com/v1/files/myorg/myproj/base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9/outgoing",
  "_self": "https://nexus.example.com/v1/files/myorg/myproj/base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/file.json",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 1,
  "_deprecated": false,
  "_createdAt": "2019-01-28T12:15:33.238Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-01-28T12:15:33.238Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub

Update a file

This operation overrides the payload.

In order to ensure a client does not perform any changes to a file without having had seen the previous revision of the file, the last revision needs to be passed as a query parameter.

PUT /v1/files/{org_label}/{project_label}/{resource_id}?rev={previous_rev}

… where {previous_rev} is the last known revision number for the resource.

Example

Request
curl -XPUT -F "file=@/path/to/myfile2.png;type=image/png" "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile.jpg?rev=1"
Full source at GitHub
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "nxv:myfile",
  "@type": "File",
  "_bytes": 2670,
  "_digest": {
    "_algorithm": "SHA-256",
    "_value": "25fc54fba0beec17a598b5a68420ded1595b2f76f0a0b7c6077792ece828bc2e"
  },
  "_filename": "myfile2.png",
  "_mediaType": "image/png",
  "_incoming": "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile/incoming",
  "_outgoing": "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile/outgoing",
  "_self": "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/file.json",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 2,
  "_deprecated": false,
  "_createdAt": "2019-01-28T12:15:33.238Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-01-28T12:15:33.238Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub

Tag a file

Links a file revision to a specific name.

Tagging a file is considered to be an update as well.

POST /v1/files/{org_label}/{project_label}/{file_id}/tags?rev={previous_rev}
  {
    "tag": "{name}",
    "rev": {rev}
  }

… where

  • {previous_rev}: is the last known revision number for the file.
  • {name}: String - label given to the file at specific revision.
  • {rev}: Number - the revision to link the provided {name}.

Example

Request
curl -XPOST -H "Content-Type: application/json" "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile/tags?rev=2" -d \
'{
  "tag": "mytag",
  "rev": 1
}'
Full source at GitHub
Payload
{
  "tag": "mytag",
  "rev": 1
}
Full source at GitHub
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "nxv:myfile",
  "@type": "File",
  "_bytes": 2670,
  "_digest": {
    "_algorithm": "SHA-256",
    "_value": "25fc54fba0beec17a598b5a68420ded1595b2f76f0a0b7c6077792ece828bc2e"
  },
  "_filename": "myfile2.png",
  "_mediaType": "image/png",
  "_incoming": "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile/incoming",
  "_outgoing": "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile/outgoing",
  "_self": "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/file.json",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 3,
  "_deprecated": false,
  "_createdAt": "2019-01-28T12:15:33.238Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-10-28T12:15:33.238Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub

Deprecate a file

Locks the file, so no further operations can be performed.

Deprecating a file is considered to be an update as well.

DELETE /v1/files/{org_label}/{project_label}?rev={previous_rev}

… where {previous_rev} is the last known revision number for the file.

Example

Request
curl -XDELETE "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile/tags?rev=3"
Full source at GitHub
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "nxv:myfile",
  "@type": "File",
  "_bytes": 2670,
  "_digest": {
    "_algorithm": "SHA-256",
    "_value": "25fc54fba0beec17a598b5a68420ded1595b2f76f0a0b7c6077792ece828bc2e"
  },
  "_filename": "myfile2.png",
  "_mediaType": "image/png",
  "_incoming": "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile/incoming",
  "_outgoing": "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile/outgoing",
  "_self": "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/file.json",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 4,
  "_deprecated": true,
  "_createdAt": "2019-01-28T12:15:33.238Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-12-28T12:15:33.238Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub

Fetch a file

When fetching a file, the response format can be chosen through HTTP content negotiation, using the Accept HTTP header.

  • application/ld+json: JSON-LD output response to retrieve the file metadata. Further specifying the query parameter format=compacted|expanded will provide with the JSON-LD compacted document form or the expanded document form.
  • */*: retrieves the file content.
  • for any other Content-Type that matches the file Content-Type, the file content will be fetched as well.
GET /v1/files/{org_label}/{project_label}/{file_id}?rev={rev}&tag={tag}

where …

  • {rev}: Number - the targeted revision to be fetched. This field is optional and defaults to the latest revision.
  • {tag}: String - the targeted tag to be fetched. This field is optional.

{rev} and {tag} fields cannot be simultaneously present.

Example

Request (binary)
curl "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile.jpg"
Full source at GitHub
Request (metadata)
curl -H "Accept: application/json" "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile.jpg"
Full source at GitHub
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "nxv:myfile",
  "@type": "File",
  "_bytes": 2670,
  "_digest": {
    "_algorithm": "SHA-256",
    "_value": "25fc54fba0beec17a598b5a68420ded1595b2f76f0a0b7c6077792ece828bc2e"
  },
  "_filename": "myfile2.png",
  "_mediaType": "image/png",
  "_storage": {
    "@id": "https://nexus.example.com/v1/resources/myorg/myproj/_/myStorage",
    "_rev": 1
  },
  "_incoming": "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile/incoming",
  "_outgoing": "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile/outgoing",
  "_self": "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/file.json",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 4,
  "_deprecated": true,
  "_createdAt": "2019-01-28T12:15:33.238Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-12-28T12:15:33.238Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub

List files

GET /v1/files/{org_label}/{project_label}?from={from}&size={size}&deprecated={deprecated}&rev={rev}&type={type}&createdBy={createdBy}&updatedBy={updatedBy}&q={search}

where…

  • {from}: Number - is the parameter that describes the offset for the current query; defaults to 0
  • {size}: Number - is the parameter that limits the number of results; defaults to 20
  • {deprecated}: Boolean - can be used to filter the resulting files based on their deprecation status
  • {rev}: Number - can be used to filter the resulting files based on their revision value
  • {type}: Iri - can be used to filter the resulting files based on their @type value. This parameter can appear multiple times, filtering further the @type value.
  • {createdBy}: Iri - can be used to filter the resulting files based on their creator
  • {updatedBy}: Iri - can be used to filter the resulting files based on the person which performed the last update
  • {search}: String - can be provided to select only the files in the collection that have attribute values matching (containing) the provided string

Example

Request
curl "https://nexus.example.com/v1/files/myorg/myproj"
Full source at GitHub
Response
{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/search.json",
    "https://bluebrain.github.io/nexus/contexts/resource.json"
  ],
  "_total": 2,
  "_results": [
    {
      "@id": "https://bluebrain.github.io/nexus/vocabulary/myfile",
      "@type": "https://bluebrain.github.io/nexus/vocabulary/File",
      "_bytes": 670,
      "_digest": {
        "_algorithm": "SHA-256",
        "_value": "25fc54fba0beec17a598b5a68420ded1595b2f76f0a0b7c6077792ece828bc2e"
      },
      "_filename": "myfile.jpg",
      "_storage": {
        "@id": "https://nexus.example.com/v1/resources/myorg/myproj/_/myStorage",
        "_rev": 1
      },
      "_mediaType": "image/jpeg",
      "_incoming": "https://nexus.example.com/v1/files/myorg/myproj/https%3A%2F%2Fbluebrain.github.io%2Fnexus%2Fvocabulary%2Fmyfile/incoming",
      "_outgoing": "https://nexus.example.com/v1/files/myorg/myproj/https%3A%2F%2Fbluebrain.github.io%2Fnexus%2Fvocabulary%2Fmyfile/outgoing",
      "_self": "https://nexus.example.com/v1/files/myorg/myproj/https%3A%2F%2Fbluebrain.github.io%2Fnexus%2Fvocabulary%2Fmyfile",
      "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/file.json",
      "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
      "_rev": 4,
      "_deprecated": true,
      "_createdAt": "2019-01-28T12:15:33.238Z",
      "_createdBy": "https://nexus.example.com/v1/anonymous",
      "_updatedAt": "2019-01-28T12:15:33.238Z",
      "_updatedBy": "https://nexus.example.com/v1/anonymous"
    },
    {
      "@id": "https://nexus.example.com/mybase/d8848d4c-68f7-4ffd-952f-63a8cbcb86a9",
      "@type": "https://bluebrain.github.io/nexus/vocabulary/File",
      "_bytes": 2670,
      "_digest": {
        "_algorithm": "SHA-256",
        "_value": "25fc54fba0beec17a598b5a68420ded1595b2f76f0a0b7c6077792ece828bc2e"
      },
      "_storage": {
        "@id": "https://nexus.example.com/v1/resources/myorg/myproj/_/myStorage",
        "_rev": 1
      },
      "_filename": "myfile2.png",
      "_mediaType": "image/png",
      "_incoming": "https://nexus.example.com/v1/files/myorg/myproj/https%3A%2F%2Fnexus.example.com%2Fmybase%2Fd8848d4c-68f7-4ffd-952f-63a8cbcb86a9/incoming",
      "_outgoing": "https://nexus.example.com/v1/files/myorg/myproj/https%3A%2F%2Fnexus.example.com%2Fmybase%2Fd8848d4c-68f7-4ffd-952f-63a8cbcb86a9/outgoing",
      "_self": "https://nexus.example.com/v1/files/myorg/myproj/https%3A%2F%2Fnexus.example.com%2Fmybase%2Fd8848d4c-68f7-4ffd-952f-63a8cbcb86a9",
      "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/file.json",
      "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
      "_rev": 1,
      "_deprecated": false,
      "_createdAt": "2019-01-28T12:15:33.238Z",
      "_createdBy": "https://nexus.example.com/v1/anonymous",
      "_updatedAt": "2019-12-28T12:15:33.238Z",
      "_updatedBy": "https://nexus.example.com/v1/anonymous"
    }
  ],
  "_next": "https://nexus.example.com/v1/files/myorg/myproj?after=%5B1559045718752,%22https://nexus.example.com/mybase/d8848d4c-68f7-4ffd-952f-63a8cbcb86a9%22%5D"
}
Full source at GitHub