Snapshot version

You are browsing the docs for the snapshot version of Nexus, the latest release is available here

Projects

Projects belong to an organization and are rooted in the corresponding /v1/projects/{org_label} path. The purposes of projects are:

  • Group and categorize sub-resources.
  • Define global settings that apply for operations on all sub-resources.
  • Provide isolation from resources inside other projects. This behavior can be partially changed by defining resolvers and aggregated views [1] [2]
Authorization notes

When creating projects, the caller must have projects/create permissions on the current path of the project or the ancestor paths.

When updating projects, the caller must have projects/write permissions on the current path of the project or the ancestor paths.

When reading projects, the caller must have projects/read permissions on the current path of the project or the ancestor paths.

When deleting projects, the caller must have projects/delete permissions on the current path of the project or the ancestor paths.

Please visit Authentication & authorization section to learn more about it.

Payload

{
  "description": "{description}",
  "base": "{base}",
  "vocab": "{vocab}",
  "enforceSchema": "{enforceSchema}",
  "apiMappings": [
   {
      "prefix": "{prefix}",
      "namespace": "{namespace}"
    },
    ...
  ]
}

where…

  • {description}: String - an optional description for this project.
  • {base}: IRI - the JSON-LD @base used for generating fully qualified IRI ids when performing operations on a sub-resource URIs and payloads (when no other @base is present in the @context payload). E.g.: Let base be http://localhost:8080/. When a resource is created and no @id is present in the payload, the platform will generate an @id which will look like http://localhost:8080/{UUID}. This field is optional and will default to {{base}}/v1/resources/{org_label}/{project_label}/_/.
  • {vocab}: IRI - the JSON-LD @vocab for all unqualified predicates in children resources’ payload (when no other @vocab is present in the @context payload and the resources’ payload is not a JSON-LD aware payload). E.g. if the vocab is set to https://schema.org/, when a field a resource is created and a field name is present in the payload, it will be expanded to http://schema.org/name by the system during indexing and fetch operations. This field is optional and will default to {{base}}/v1/vocabs/{org_label}/{project_label}/.
  • {enforceSchema}: Boolean - Allows to ban the creation of unconstrained resources in this project
  • {apiMappings}: Json object - provides a convenient way to compact/expand URIs when performing operations on a sub-resource. This field is optional.

API Mappings

The apiMappings Json object array maps each prefix to its namespace. This is useful in order to generate IRI ids on API endpoints using the prefix as an alias or curie instead of a fully expanded url encoded IRI.

Note

The api mappings only apply to children resources URIs but not to their payload. Please, use the JSON-LD @context to achieve compaction/expansion on resources’ payload.

Having the following apiMappings:

{
  "apiMappings": [
   {
      "prefix": "{prefix}",
      "namespace": "{namespace}"
    },
    { ... }
  ]
}

where…

  • {prefix}: String - a curie or an alias.
  • {namespace}: IRI - the actual resolution of the prefix field.

Let’s see an example:

 {
   "apiMappings": [
    {
       "prefix": "person",
       "namespace": "http://example.com/some/person"
     },
     {
       "prefix": "schemas",
       "namespace": "https://bluebrainnexus.io/schemas/"
     }
   ]
 }

The previous project api mappings allows us to create a schema using the following endpoints:

  • /v1/schemas/{org_label}/{project_label}/person. The @id of the resulting schema will be http://example.com/some/person
  • /v1/schemas/{org_label}/{project_label}/schema:other. The @id of the resulting schema will be https://bluebrainnexus.io/schemas/other

Create

PUT /v1/projects/{org_label}/{label}
  {...}

…where {label} is the user friendly name assigned to this project. The semantics of the label should be consistent with the type of data provided by its sub-resources, since it’ll be a part of the sub-resources’ URI.

Example

Request
sourcecurl -X PUT \
   -H "Content-Type: application/json" \
   "http://localhost:8080/v1/projects/myorg/myproject" \
   -d '{
    "description": "description",
    "vocab": "https://schema.org/",
    "apiMappings": [
        {
            "prefix": "my",
            "namespace": "http://example.com/my"
        }
    ]
   }'
Payload
source{
  "description": "description",
  "vocab": "https://schema.org/",
  "apiMappings": [
    {
      "prefix": "my",
      "namespace": "http://example.com/my"
    }
  ]
}
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/projects-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/projects/myorg/myproject",
  "@type": "Project",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/projects.json",
  "_createdAt": "2021-05-10T15:43:36.567Z",
  "_createdBy": "http://localhost:8080/v1/anonymous",
  "_deprecated": false,
  "_markedForDeletion": false,
  "_effectiveApiMappings": [
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/",
      "_prefix": "nxv"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/defaultElasticSearchIndex",
      "_prefix": "documents"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/defaultInProject",
      "_prefix": "defaultResolver"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/unconstrained.json",
      "_prefix": "resource"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/unconstrained.json",
      "_prefix": "_"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/views.json",
      "_prefix": "view"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl",
      "_prefix": "schema"
    },
    {
      "_namespace": "http://example.com/my",
      "_prefix": "my"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/storages.json",
      "_prefix": "storage"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/files.json",
      "_prefix": "file"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/resolvers.json",
      "_prefix": "resolver"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/defaultSparqlIndex",
      "_prefix": "graph"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/archives.json",
      "_prefix": "archive"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/diskStorageDefault",
      "_prefix": "defaultStorage"
    }
  ],
  "_label": "myproject",
  "_organizationLabel": "myorg",
  "_organizationUuid": "41f169b8-7ae4-4878-a7ff-6309cb54ae2f",
  "_rev": 1,
  "_self": "http://localhost:8080/v1/projects/myorg/myproject",
  "_updatedAt": "2021-05-10T15:43:36.567Z",
  "_updatedBy": "http://localhost:8080/v1/anonymous",
  "_uuid": "813cfa79-75fc-48eb-b931-abb21edb082b"
}

Update

This operation overrides the project payload.

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

PUT /v1/projects/{org_label}/{label}?rev={previous_rev}
  {...}

… where

  • {previous_rev}: Number - the last known revision for the organization.
  • {label}: String - the user friendly name that identifies this project.

Example

Request
sourcecurl -X PUT \
   -H "Content-Type: application/json" \
   "http://localhost:8080/v1/projects/myorg/myproject?rev=1" \
   -d '{
    "description": "updated description",
    "vocab": "https://schema.org/"
   }'
Payload
source{
  "description": "updated description",
  "vocab": "https://schema.org/"
}
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/projects-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/projects/myorg/myproject",
  "@type": "Project",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/projects.json",
  "_createdAt": "2021-05-10T15:43:36.567Z",
  "_createdBy": "http://localhost:8080/v1/anonymous",
  "_deprecated": false,
  "_markedForDeletion": false,
  "_effectiveApiMappings": [
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/",
      "_prefix": "nxv"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/defaultElasticSearchIndex",
      "_prefix": "documents"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/defaultInProject",
      "_prefix": "defaultResolver"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl",
      "_prefix": "schema"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/unconstrained.json",
      "_prefix": "resource"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/unconstrained.json",
      "_prefix": "_"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/views.json",
      "_prefix": "view"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/storages.json",
      "_prefix": "storage"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/files.json",
      "_prefix": "file"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/resolvers.json",
      "_prefix": "resolver"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/defaultSparqlIndex",
      "_prefix": "graph"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/archives.json",
      "_prefix": "archive"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/diskStorageDefault",
      "_prefix": "defaultStorage"
    }
  ],
  "_label": "myproject",
  "_organizationLabel": "myorg",
  "_organizationUuid": "41f169b8-7ae4-4878-a7ff-6309cb54ae2f",
  "_rev": 2,
  "_self": "http://localhost:8080/v1/projects/myorg/myproject",
  "_updatedAt": "2021-05-10T15:45:20.769Z",
  "_updatedBy": "http://localhost:8080/v1/anonymous",
  "_uuid": "813cfa79-75fc-48eb-b931-abb21edb082b"
}

Deprecate

Locks the project, so no further operations (except for deletion) can be performed on it or on the children resources.

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

DELETE /v1/projects/{org_label}/{label}?rev={previous_rev}

… where

  • {previous_rev}: Number - the last known revision for the organization.
  • {label}: String - the user friendly name that identifies this project.

Example

Request
sourcecurl -X DELETE \
   "http://localhost:8080/v1/projects/myorg/myproject?rev=2"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/projects-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/projects/myorg/myproject",
  "@type": "Project",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/projects.json",
  "_createdAt": "2021-05-10T15:43:36.567Z",
  "_createdBy": "http://localhost:8080/v1/anonymous",
  "_deprecated": true,
  "_markedForDeletion": false,
  "_effectiveApiMappings": [
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/",
      "_prefix": "nxv"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/defaultElasticSearchIndex",
      "_prefix": "documents"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/defaultInProject",
      "_prefix": "defaultResolver"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl",
      "_prefix": "schema"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/unconstrained.json",
      "_prefix": "resource"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/unconstrained.json",
      "_prefix": "_"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/views.json",
      "_prefix": "view"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/storages.json",
      "_prefix": "storage"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/files.json",
      "_prefix": "file"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/resolvers.json",
      "_prefix": "resolver"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/defaultSparqlIndex",
      "_prefix": "graph"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/archives.json",
      "_prefix": "archive"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/diskStorageDefault",
      "_prefix": "defaultStorage"
    }
  ],
  "_label": "myproject",
  "_organizationLabel": "myorg",
  "_organizationUuid": "41f169b8-7ae4-4878-a7ff-6309cb54ae2f",
  "_rev": 3,
  "_self": "http://localhost:8080/v1/projects/myorg/myproject",
  "_updatedAt": "2021-05-10T15:47:40.659Z",
  "_updatedBy": "http://localhost:8080/v1/anonymous",
  "_uuid": "813cfa79-75fc-48eb-b931-abb21edb082b"
}

Undeprecate

Reverses the deprecation of a project.

Undeprecating a project is considered to be an update as well.

PUT /v1/projects/{org_label}/{label}/undeprecate?rev={previous_rev}

… where

  • {previous_rev}: Number - the last known revision for the organization.
  • {label}: String - the user friendly name that identifies this project.

Example

Request
sourcecurl -X PUT \
   "http://localhost:8080/v1/projects/myorg/myproject/undeprecate?rev=2"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/projects-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/projects/myorg/myproject",
  "@type": "Project",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/projects.json",
  "_createdAt": "2021-05-10T15:43:36.567Z",
  "_createdBy": "http://localhost:8080/v1/anonymous",
  "_deprecated": false,
  "_markedForDeletion": false,
  "_effectiveApiMappings": [
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/",
      "_prefix": "nxv"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/defaultElasticSearchIndex",
      "_prefix": "documents"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/defaultInProject",
      "_prefix": "defaultResolver"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl",
      "_prefix": "schema"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/unconstrained.json",
      "_prefix": "resource"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/unconstrained.json",
      "_prefix": "_"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/views.json",
      "_prefix": "view"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/storages.json",
      "_prefix": "storage"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/files.json",
      "_prefix": "file"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/resolvers.json",
      "_prefix": "resolver"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/defaultSparqlIndex",
      "_prefix": "graph"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/archives.json",
      "_prefix": "archive"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/diskStorageDefault",
      "_prefix": "defaultStorage"
    }
  ],
  "_label": "myproject",
  "_organizationLabel": "myorg",
  "_organizationUuid": "41f169b8-7ae4-4878-a7ff-6309cb54ae2f",
  "_rev": 3,
  "_self": "http://localhost:8080/v1/projects/myorg/myproject",
  "_updatedAt": "2021-05-10T15:47:40.659Z",
  "_updatedBy": "http://localhost:8080/v1/anonymous",
  "_uuid": "813cfa79-75fc-48eb-b931-abb21edb082b"
}

Delete

Deletes the target project and all its resources.

Once the request is processed, an asynchronous task gets triggered and deletes the data generated from each resource type (e.g.: the indices generated by the view resources, the binaries generated by the file resources). During this time, no write operation can be performed at the project level nor at the resources level for the target project. When the task is finished, the target project can be recreated if desired.

Deletion only works when the configuration flag app.projects.deletion.enabled is set to true and the current project is not referenced somewhere else (e.g.: in a CrossProjectResolver, an AggregatedView, etc.).

DELETE /v1/projects/{org_label}/{label}?rev={previous_rev}&prune=true

… where

  • {previous_rev}: Number - the last known revision for the organization.
  • {label}: String - the user friendly name that identifies this project.
Request
sourcecurl -L -X DELETE \
   "http://localhost:8080/v1/projects/myorg/myproject?rev=2&prune=true"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/projects-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/projects/myorg/myproject",
  "@type": "Project",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/projects.json",
  "_createdAt": "2021-05-10T15:43:36.567Z",
  "_createdBy": "http://localhost:8080/v1/anonymous",
  "_deprecated": false,
  "_markedForDeletion": true,
  "_effectiveApiMappings": [
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/",
      "_prefix": "nxv"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/defaultElasticSearchIndex",
      "_prefix": "documents"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/defaultInProject",
      "_prefix": "defaultResolver"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl",
      "_prefix": "schema"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/unconstrained.json",
      "_prefix": "resource"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/unconstrained.json",
      "_prefix": "_"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/views.json",
      "_prefix": "view"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/storages.json",
      "_prefix": "storage"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/files.json",
      "_prefix": "file"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/resolvers.json",
      "_prefix": "resolver"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/defaultSparqlIndex",
      "_prefix": "graph"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/archives.json",
      "_prefix": "archive"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/diskStorageDefault",
      "_prefix": "defaultStorage"
    }
  ],
  "_label": "myproject",
  "_organizationLabel": "myorg",
  "_organizationUuid": "41f169b8-7ae4-4878-a7ff-6309cb54ae2f",
  "_rev": 3,
  "_self": "http://localhost:8080/v1/projects/myorg/myproject",
  "_updatedAt": "2021-05-10T15:47:40.659Z",
  "_updatedBy": "http://localhost:8080/v1/anonymous",
  "_uuid": "813cfa79-75fc-48eb-b931-abb21edb082b"
}

Fetch (current version)

GET /v1/projects/{org_label}/{label}

…where {label} is the user friendly name that identifies this project.

Example

Request
sourcecurl "http://localhost:8080/v1/projects/myorg/myproject"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/projects.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/projects/myorg/myproject",
  "@type": "Project",
  "apiMappings": [],
  "base": "http://localhost:8080/v1/resources/myorg/myproject/_/",
  "description": "updated description",
  "vocab": "https://schema.org/",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/projects.json",
  "_createdAt": "2021-05-10T15:43:36.567Z",
  "_createdBy": "http://localhost:8080/v1/anonymous",
  "_markedForDeletion": false,
  "_effectiveApiMappings": [
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/",
      "_prefix": "nxv"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/defaultElasticSearchIndex",
      "_prefix": "documents"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/defaultInProject",
      "_prefix": "defaultResolver"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl",
      "_prefix": "schema"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/unconstrained.json",
      "_prefix": "resource"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/unconstrained.json",
      "_prefix": "_"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/views.json",
      "_prefix": "view"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/storages.json",
      "_prefix": "storage"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/files.json",
      "_prefix": "file"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/resolvers.json",
      "_prefix": "resolver"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/defaultSparqlIndex",
      "_prefix": "graph"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/archives.json",
      "_prefix": "archive"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/diskStorageDefault",
      "_prefix": "defaultStorage"
    }
  ],
  "_label": "myproject",
  "_organizationLabel": "myorg",
  "_organizationUuid": "41f169b8-7ae4-4878-a7ff-6309cb54ae2f",
  "_rev": 3,
  "_self": "http://localhost:8080/v1/projects/myorg/myproject",
  "_updatedAt": "2021-05-10T15:47:40.659Z",
  "_updatedBy": "http://localhost:8080/v1/anonymous",
  "_uuid": "813cfa79-75fc-48eb-b931-abb21edb082b"
}

If the redirect to Fusion feature is enabled and if the Accept header is set to text/html, a redirection to the fusion representation of the project will be returned.

Fetch (specific version)

GET /v1/projects/{org_label}/{label}?rev={rev}

…where

  • {label}: String - the user friendly name that identifies this project.
  • {rev}: Number - the revision of the project to be retrieved.

Example

Request
sourcecurl "http://localhost:8080/v1/projects/myorg/myproject?rev=1"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/projects.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/projects/myorg/myproject",
  "@type": "Project",
  "apiMappings": [
    {
      "namespace": "http://example.com/my",
      "prefix": "my"
    }
  ],
  "base": "http://localhost:8080/v1/resources/myorg/myproject/_/",
  "description": "description",
  "vocab": "https://schema.org/",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/projects.json",
  "_createdAt": "2021-05-10T15:43:36.567Z",
  "_createdBy": "http://localhost:8080/v1/anonymous",
  "_deprecated": false,
  "_markedForDeletion": false,
  "_effectiveApiMappings": [
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/",
      "_prefix": "nxv"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/defaultElasticSearchIndex",
      "_prefix": "documents"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/defaultInProject",
      "_prefix": "defaultResolver"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/unconstrained.json",
      "_prefix": "resource"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/unconstrained.json",
      "_prefix": "_"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/views.json",
      "_prefix": "view"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl",
      "_prefix": "schema"
    },
    {
      "_namespace": "http://example.com/my",
      "_prefix": "my"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/storages.json",
      "_prefix": "storage"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/files.json",
      "_prefix": "file"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/resolvers.json",
      "_prefix": "resolver"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/defaultSparqlIndex",
      "_prefix": "graph"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/schemas/archives.json",
      "_prefix": "archive"
    },
    {
      "_namespace": "https://bluebrain.github.io/nexus/vocabulary/diskStorageDefault",
      "_prefix": "defaultStorage"
    }
  ],
  "_label": "myproject",
  "_organizationLabel": "myorg",
  "_organizationUuid": "41f169b8-7ae4-4878-a7ff-6309cb54ae2f",
  "_rev": 1,
  "_self": "http://localhost:8080/v1/projects/myorg/myproject",
  "_updatedAt": "2021-05-10T15:43:36.567Z",
  "_updatedBy": "http://localhost:8080/v1/anonymous",
  "_uuid": "813cfa79-75fc-48eb-b931-abb21edb082b"
}

List

GET /v1/projects?from={from}
                 &size={size}
                 &deprecated={deprecated}
                 &rev={rev}
                 &createdBy={createdBy}
                 &updatedBy={updatedBy}
                 &label={label}
                 &sort={sort}

or the variation to filter a specific organization {org_label}:

GET /v1/projects/{org_label}?from={from}
                             &size={size}
                             &deprecated={deprecated}
                             &rev={rev}
                             &createdBy={createdBy}
                             &updatedBy={updatedBy}
                             &label={label}
                             &sort={sort}

where…

  • {from}: Number - the offset from which to start the listings. Defaults to 0
  • {size}: Number - the maximum amount fo results to be returned. Defaults to 30
  • {deprecated}: Boolean - filter the resulting projects based on their deprecation status. Optional parameter.
  • {rev}: Number - filter the resulting projects based on their revision value. Optional parameter.
  • {createdBy}: Iri - filter the resulting projects based on their creator. Optional parameter.
  • {updatedBy}: Iri - filter the resulting projects based on the person which performed the last update. Optional parameter.
  • {label}: String - filter the resulting projects based on its label. E.g.: label=my will match any project’s label that contains the string my. Optional parameter.
  • {sort}: String - orders the resulting projects based on its metadata fields. Optional parameter that can appear multiple times, further specifying the ordering criteria. Defaults to _createdAt, ordering projects by creation date.

Example

Request
sourcecurl "http://localhost:8080/v1/projects?label=my"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/metadata.json",
    "https://bluebrain.github.io/nexus/contexts/search.json",
    "https://bluebrain.github.io/nexus/contexts/projects.json"
  ],
  "_total": 1,
  "_results": [
    {
      "@id": "http://localhost:8080/v1/projects/myorg/myproject",
      "@type": "Project",
      "apiMappings": [],
      "base": "http://localhost:8080/v1/resources/myorg/myproject/_/",
      "description": "updated description",
      "vocab": "https://schema.org/",
      "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/projects.json",
      "_createdAt": "2021-05-10T15:43:36.567Z",
      "_createdBy": "http://localhost:8080/v1/anonymous",
      "_deprecated": true,
      "_markedForDeletion": false,
      "_effectiveApiMappings": [
        {
          "_namespace": "https://bluebrain.github.io/nexus/vocabulary/",
          "_prefix": "nxv"
        },
        {
          "_namespace": "https://bluebrain.github.io/nexus/vocabulary/defaultElasticSearchIndex",
          "_prefix": "documents"
        },
        {
          "_namespace": "https://bluebrain.github.io/nexus/vocabulary/defaultInProject",
          "_prefix": "defaultResolver"
        },
        {
          "_namespace": "https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl",
          "_prefix": "schema"
        },
        {
          "_namespace": "https://bluebrain.github.io/nexus/schemas/unconstrained.json",
          "_prefix": "resource"
        },
        {
          "_namespace": "https://bluebrain.github.io/nexus/schemas/unconstrained.json",
          "_prefix": "_"
        },
        {
          "_namespace": "https://bluebrain.github.io/nexus/schemas/views.json",
          "_prefix": "view"
        },
        {
          "_namespace": "https://bluebrain.github.io/nexus/schemas/storages.json",
          "_prefix": "storage"
        },
        {
          "_namespace": "https://bluebrain.github.io/nexus/schemas/files.json",
          "_prefix": "file"
        },
        {
          "_namespace": "https://bluebrain.github.io/nexus/schemas/resolvers.json",
          "_prefix": "resolver"
        },
        {
          "_namespace": "https://bluebrain.github.io/nexus/vocabulary/defaultSparqlIndex",
          "_prefix": "graph"
        },
        {
          "_namespace": "https://bluebrain.github.io/nexus/schemas/archives.json",
          "_prefix": "archive"
        },
        {
          "_namespace": "https://bluebrain.github.io/nexus/vocabulary/diskStorageDefault",
          "_prefix": "defaultStorage"
        }
      ],
      "_label": "myproject",
      "_organizationLabel": "myorg",
      "_organizationUuid": "41f169b8-7ae4-4878-a7ff-6309cb54ae2f",
      "_rev": 3,
      "_self": "http://localhost:8080/v1/projects/myorg/myproject",
      "_updatedAt": "2021-05-10T15:47:40.659Z",
      "_updatedBy": "http://localhost:8080/v1/anonymous",
      "_uuid": "813cfa79-75fc-48eb-b931-abb21edb082b"
    }
  ]
}

List deletions

Lists all the projects that were deleted or are in the process to be deleted.

GET /v1/projects/deletions
Request
sourcecurl  "http://localhost:8080/v1/projects/deletions"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/metadata.json",
    "https://bluebrain.github.io/nexus/contexts/search.json",
    "https://bluebrain.github.io/nexus/contexts/deletion-status.json"
  ],
  "_total": 1,
  "_results": [
    {
      "progress": "ResourcesDeleted",
      "_createdAt": "2021-08-31T12:50:48.305Z",
      "_createdBy": "http://localhost:8080/v1/anonymous",
      "_finished": true,
      "_project": "myorg/myproject",
      "_projectCreatedAt": "2021-08-31T12:49:19.404Z",
      "_projectCreatedBy": "http://localhost:8080/v1/anonymous",
      "_self": "http://localhost:8080/v1/projects/myorg/myproject/deletions/5d4e830b-39ad-4c8f-8c28-f63a94fbad63",
      "_updatedAt": "2021-08-31T12:50:55.305Z",
      "_uuid": "5d4e830b-39ad-4c8f-8c28-f63a94fbad63"
    }
  ]
}

Server Sent Events

This endpoint allows clients to receive automatic updates from the projects in a streaming fashion.

GET /v1/projects/events

where Last-Event-Id is an optional HTTP Header that identifies the last consumed project event. It can be used for cases when a client does not want to retrieve the whole event stream, but to start after a specific event.

The response contains a series of project events, represented in the following way

data:{payload}
event:{type}
id:{id}

where…

  • {payload}: Json - is the actual payload of the current project
  • {type}: String - is a type identifier for the current project. Possible types are: ProjectCreated, ProjectUpdated and ProjectDeprecated
  • {id}: String - is the identifier of the project event. It can be used in the Last-Event-Id HTTP Header

Example

Request
sourcecurl "http://localhost:8080/v1/projects/events"
Response
sourcedata:{"@context":["https://bluebrain.github.io/nexus/contexts/metadata.json","https://bluebrain.github.io/nexus/contexts/projects.json"],"@type":"ProjectCreated","apiMappings":[{"namespace":"http://example.com/my","prefix":"my"}],"base":"http://localhost:8080/v1/resources/myorg/myproject/_/","description":"description","vocab":"https://schema.org/","_instant":"2021-05-10T15:43:36.567Z","_label":"myproject","_organizationLabel":"myorg","_projectId":"http://localhost:8080/v1/projects/myorg/myproject","_resourceId":"http://localhost:8080/v1/projects/myorg/myproject","_rev":1,"_subject":"http://localhost:8080/v1/anonymous","_uuid":"813cfa79-75fc-48eb-b931-abb21edb082b"}
event:ProjectCreated
id:7bdd4bc0-b1a6-11eb-a162-35a8ee728fbb

data:{"@context":["https://bluebrain.github.io/nexus/contexts/metadata.json","https://bluebrain.github.io/nexus/contexts/projects.json"],"@type":"ProjectUpdated","apiMappings":[],"base":"http://localhost:8080/v1/resources/myorg/myproject/_/","description":"updated description","vocab":"https://schema.org/","_instant":"2021-05-10T15:45:20.769Z","_label":"myproject","_organizationLabel":"myorg","_projectId":"http://localhost:8080/v1/projects/myorg/myproject","_resourceId":"http://localhost:8080/v1/projects/myorg/myproject","_rev":2,"_subject":"http://localhost:8080/v1/anonymous","_uuid":"813cfa79-75fc-48eb-b931-abb21edb082b"}
event:ProjectUpdated
id:b9f8a620-b1a6-11eb-a162-35a8ee728fbb

data:{"@context":["https://bluebrain.github.io/nexus/contexts/metadata.json","https://bluebrain.github.io/nexus/contexts/projects.json"],"@type":"ProjectDeprecated","_instant":"2021-05-10T15:47:40.659Z","_label":"myproject","_organizationLabel":"myorg","_projectId":"http://localhost:8080/v1/projects/myorg/myproject","_resourceId":"http://localhost:8080/v1/projects/myorg/myproject","_rev":3,"_subject":"http://localhost:8080/v1/anonymous","_uuid":"813cfa79-75fc-48eb-b931-abb21edb082b"}
event:ProjectDeprecated
id:0d5a5250-b1a7-11eb-a162-35a8ee728fbb

Fetch statistics

Note

This endpoint is experimental and the response structure might change in the future.

GET /v1/projects/{org_label}/{label}/statistics

It returns:

  • the dateTime of the latest consumed event (lastProcessedEventDateTime).
  • the number of consumed events (eventsCount).
  • the number of consumed resources (resourcesCount). A resource might be made of multiple events (create, update, deprecate), so this number will always be smaller or equal to eventsCount.

Example

Request
sourcecurl "http://localhost:8080/v1/projects/myorg/myproject/statistics"
Response
source{
  "@context": "https://bluebrain.github.io/nexus/contexts/statistics.json",
  "lastProcessedEventDateTime": "2021-05-10T00:00:00Z",
  "eventsCount": 10,
  "resourcesCount": 8
}

Automatic project deletion

Note

This endpoint is experimental and the response structure might change in the future.

The functionality is provided through the project-deletion plugin that is bundled with the software, but disabled by default. Due to the risk of inadvertently deleting unwanted projects, the plugin is disabled by default, but also provided in a different location than the default plugin location (the disabled sub-folder in the plugins folder).

The plugin can be enabled by sym-linking or copying the plugin to the plugins folder and the configuring the plugin accordingly:

  • enable the plugin -Dplugins.project-deletion.enabled=true
  • adjust the inclusion and exclusion filters -Dplugins.project-deletion.included-projects.1=".+"" and -Dplugins.project-deletion.excluded-projects.1=".+protected.+""

For details on available configuration, please visit the plugin configuration.

GET /v1/project-deletion/config

It returns the configuration of the project deletion plugin.

Example

Request
sourcecurl "http://localhost:8080/v1/project-deletion/config"
Response
source{
  "@context": "https://bluebrain.github.io/nexus/contexts/project-deletion.json",
  "@type": "ProjectDeletionConfig",
  "_idleIntervalInSeconds": 2592000,
  "_idleCheckPeriodInSeconds": 3600,
  "_deleteDeprecatedProjects": true,
  "_includedProjects": [
    "some.+"
  ],
  "_excludedProjects": [
    "retained.+"
  ]
}
Snapshot