Resources

Generic resources are rooted in the /v1/resources/{org_label}/{project_label}/{schema_id} collection.

Each resource…

  • belongs to a project identifier by the label {project_label}
  • inside an organization identifier by the label {org_label}
  • it is validated against a schema with id {schema_id}. In case of using _ for this segment, the schema segment reads as irrelevant.
Authorization notes

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

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

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

Remote contexts

Remote contexts are only resolved during creates and updates. That means that when those get updated, the resources importing them must be also updated to take them into account in a new version.

Reserved types and fields

A generic resource can not have a type belonging to the Nexus vocabulary https://bluebrain.github.io/nexus/vocabulary/.

Moreover it can not include any field starting with underscore (_) at the root level as these fields are reserved for Nexus metadata.

Nexus metadata

When using the endpoints described on this page, the responses will contain global metadata described on the Nexus Metadata page. In addition, the following resource specific metadata can be present

  • _project: address of the resource’s project
  • _incoming: address to query to obtain the list of incoming links
  • _outgoing: address to query to obtain the list of outgoing links
  • _constrainedBy: @id of the schema used to validate the resource; the schema can only be identified uniquely together with _schemaProject. If no schema has been used to validate the resource, it will indicate the unconstrained identifier.
  • _schemaProject: address of the project where the _constrainedBy schema is found

Indexing

All the API calls modifying a resource (creation, update, tagging, deprecation) can specify whether the resource should be indexed synchronously or in the background. This behaviour is controlled using indexing query param, which can be one of two values:

  • async - (default value) the resource will be indexed asynchronously
  • sync - the resource will be indexed synchronously and the API call won’t return until the indexing is finished

Create using POST

POST /v1/resources/{org_label}/{project_label}/{schema_id}?tag={tag}
  {...}

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}).

The {schema_id} segment allows to define an existing SHACL schema to validate the resource with:

  • If _ is provided, no SHACL validation will be performed
  • If another value is provided, Nexus will attempt to resolve the schema then validate the expanded JSON-LD value generated from the provided payload.

The {tag} param is an optional tag associated with the first revision of this resource

Example

Request
sourcecurl -X POST \
     -H "Content-Type: application/json" \
     "http://localhost:8080/v1/resources/myorg/myproj/myschema" \
     -d \
'{
  "@context": {
    "ex": "http://localhost:8080/",
    "@vocab": "http://localhost:8080/"
  },
  "@type": "ex:Custom",
  "name": "Alex",
  "number": 24,
  "bool": false
}'
Payload
source{
  "@context": {
    "ex": "http://localhost:8080/",
    "@vocab": "http://localhost:8080/"
  },
  "@type": "ex:Custom",
  "name": "Alex",
  "number": 24,
  "bool": false
}
Response
source{
  "@context": "https://bluebrain.github.io/nexus/contexts/metadata.json",
  "@id": "http://localhost:8080/v1/resources/myorg/myproj/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "@type": "http://localhost:8080/Custom",
  "_incoming": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/incoming",
  "_outgoing": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/outgoing",
  "_self": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resource",
  "_project": "http://localhost:8080/v1/projects/myorg/myproj",
  "_schemaProject": "http://localhost:8080/v1/projects/myorg/myproj",
  "_rev": 1,
  "_deprecated": false,
  "_createdAt": "2021-04-17T14:54:42.939Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
  "_updatedAt": "2021-04-17T14:54:42.939Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
}

Create 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/resources/{org_label}/{project_label}/{schema_id}/{resource_id}?tag={tag}
  {...}

… where {tag} is an optional tag associated with the first revision of this resource.

The {schema_id} has the same behaviour as the creation using post operation.

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

Example

Request
sourcecurl -X PUT \
     -H "Content-Type: application/json" \
     "http://localhost:8080/resources/myorg/myproj/myschema/base:fd8a2b32-170e-44e8-808f-44a8cbbc49b0" \
     -d \
'{
  "@context": {
    "ex": "http://localhost:8080/",
    "@vocab": "http://localhost:8080/"
  },
  "@type": "ex:Custom",
  "name": "Alex",
  "number": 24,
  "bool": false
}'
Payload
source{
  "@context": {
    "ex": "http://localhost:8080/",
    "@vocab": "http://localhost:8080/"
  },
  "@type": "ex:Custom",
  "name": "Alex",
  "number": 24,
  "bool": false
}
Response
source{
  "@context": "https://bluebrain.github.io/nexus/contexts/metadata.json",
  "@id": "http://localhost:8080/v1/resources/myorg/myproj/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "@type": "http://localhost:8080/Custom",
  "_incoming": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/incoming",
  "_outgoing": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/outgoing",
  "_self": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resource",
  "_project": "http://localhost:8080/v1/projects/myorg/myproj",
  "_schemaProject": "http://localhost:8080/v1/projects/myorg/myproj",
  "_rev": 1,
  "_deprecated": false,
  "_createdAt": "2021-04-17T14:54:42.939Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
  "_updatedAt": "2021-04-17T14:54:42.939Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
}

Update

A update operation which does not result in a change of the existing resources is ignored

If the submitted update does not result in changes compared to the current revision of the resource, it will be ignored and the current revision will be returned to the user.

Nevertheless, if a tag is provided, it will still be applied to the current revision of the resource.

This operation overrides the payload.

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

PUT /v1/resources/{org_label}/{project_label}/{schema_id}/{resource_id}?rev={previous_rev}&tag={tag}
  {...}

… where

  • {previous_rev} is the last known revision number for the resource.
  • {tag} is an optional tag associated with the same revision as the current update. For example, if previous_rev is 2, both the updated payload and tag will be associated with revision 3; the new latest revision.

The {schema_id} segment allows to define an existing SHACL schema to validate the resource with:

  • If _ is provided, no SHACL validation will be performed with the latest version of its current schema
  • If another value is provided, it has to match the identifier of the current schema as changing the schema of a resource is not currently supported. A different revision or tag of this schema can be provided though.

Example

Request
sourcecurl -X PUT \
     -H "Content-Type: application/json" \
     "http://localhost:8080/v1/resources/myorg/myproj/myschema/base:fd8a2b32-170e-44e8-808f-44a8cbbc49b0?rev=1" \
     -d \
'{
  "@context": {
    "ex": "http://localhost:8080/",
    "@vocab": "http://localhost:8080/"
  },
  "@type": "ex:Custom",
  "name": "Alex",
  "number": 24,
  "bool": false
}'
Payload
source{
  "@context": {
    "ex": "http://localhost:8080/",
    "@vocab": "http://localhost:8080/"
  },
  "@type": "ex:Custom",
  "name": "Alex",
  "number": 24,
  "bool": false
}
Response
source{
  "@context": "https://bluebrain.github.io/nexus/contexts/metadata.json",
  "@id": "http://localhost:8080/v1/resources/myorg/myproj/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "@type": "http://localhost:8080/Custom",
  "_incoming": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/incoming",
  "_outgoing": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/outgoing",
  "_self": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resource",
  "_project": "http://localhost:8080/v1/projects/myorg/myproj",
  "_schemaProject": "http://localhost:8080/v1/projects/myorg/myproj",
  "_rev": 2,
  "_deprecated": false,
  "_createdAt": "2021-04-17T14:54:42.939Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
  "_updatedAt": "2021-04-17T14:56:42.939Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
}

Refresh

A refresh operation which does not result in a change of the existing resources is ignored

If the refresh does not result in changes compared to the current revision of the resource, the update will be ignored and the current revision will be returned to the user.

If the submitted update does not result in changes compared to the current revision of the resource, it will be ignored and the current revision will be returned to the user.

Nevertheless, if a tag is provided, it will still be applied to the current revision of the resource.

@@@

This operation refreshes the compacted and expanded representations of the resource.

This is equivalent of doing an update with the same source as the last revision of the resource. It is useful when the schema or project contexts have changed, in order for the changes to be reflected in the resource.

PUT /v1/resources/{org_label}/{project_label}/{schema_id}/{resource_id}/refresh

Example

Request
sourcecurl -X PUT \
     "http://localhost:8080/v1/resources/myorg/myproj/myschema/base:fd8a2b32-170e-44e8-808f-44a8cbbc49b0"
Response
source{
  "@context": "https://bluebrain.github.io/nexus/contexts/metadata.json",
  "@id": "http://localhost:8080/v1/resources/myorg/myproj/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "@type": "http://localhost:8080/Custom",
  "_incoming": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/incoming",
  "_outgoing": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/outgoing",
  "_self": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resource",
  "_project": "http://localhost:8080/v1/projects/myorg/myproj",
  "_schemaProject": "http://localhost:8080/v1/projects/myorg/myproj",
  "_rev": 2,
  "_deprecated": false,
  "_createdAt": "2021-04-17T14:54:42.939Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
  "_updatedAt": "2021-04-17T14:56:42.939Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
}

Tag

Links a resource revision to a specific name.

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

POST /v1/resources/{org_label}/{project_label}/{schema_id}/{resource_id}/tags?rev={previous_rev}
  {
    "tag": "{name}",
    "rev": {rev}
  }

… where

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

Example

Request
sourcecurl -X POST \
     -H "Content-Type: application/json" \
     "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/tags?rev=2" \
     -d \
'{
  "tag": "mytag",
  "rev": 1
}'
Payload
source{
  "tag": "mytag",
  "rev": 1
}
Response
source{
  "@context": "https://bluebrain.github.io/nexus/contexts/metadata.json",
  "@id": "http://localhost:8080/v1/resources/myorg/myproj/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "@type": "http://localhost:8080/Custom",
  "_incoming": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/incoming",
  "_outgoing": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/outgoing",
  "_self": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resource",
  "_project": "http://localhost:8080/v1/projects/myorg/myproj",
  "_schemaProject": "http://localhost:8080/v1/projects/myorg/myproj",
  "_rev": 3,
  "_deprecated": false,
  "_createdAt": "2021-04-17T14:54:42.939Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
  "_updatedAt": "20121-04-17T14:58:42.939Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
}

Remove tag

Removes a given tag.

Removing a tag is considered to be an update as well.

DELETE /v1/resources/{org_label}/{project_label}/{schema_id}/{resource_id}/tags/{tag_name}?rev={previous_rev}

… where

  • {previous_rev}: is the last known revision number for the resource.
  • {tag_name}: String - label of the tag to remove.

Example

Request
sourcecurl -X DELETE \
     "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/tags/mytag?rev=2"
Response
source{
  "@context": "https://bluebrain.github.io/nexus/contexts/metadata.json",
  "@id": "http://localhost:8080/v1/resources/myorg/myproj/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "@type": "http://localhost:8080/Custom",
  "_incoming": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/incoming",
  "_outgoing": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/outgoing",
  "_self": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resource",
  "_project": "http://localhost:8080/v1/projects/myorg/myproj",
  "_schemaProject": "http://localhost:8080/v1/projects/myorg/myproj",
  "_rev": 3,
  "_deprecated": false,
  "_createdAt": "2021-04-17T14:54:42.939Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
  "_updatedAt": "20121-04-17T14:58:42.939Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
}

Deprecate

Locks the resource, so no further operations can be performed. It also deletes the resource from listing/querying results.

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

DELETE /v1/resources/{org_label}/{project_label}/{schema_id}/{resource_id}?rev={previous_rev}

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

Example

Request
sourcecurl -X DELETE \
     -H "Content-Type: application/json" \
     "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0?rev=3"
Response
source{
  "@context": "https://bluebrain.github.io/nexus/contexts/metadata.json",
  "@id": "http://localhost:8080/v1/resources/myorg/myproj/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "@type": "http://localhost:8080/Custom",
  "_incoming": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/incoming",
  "_outgoing": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/outgoing",
  "_self": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resource",
  "_project": "http://localhost:8080/v1/projects/myorg/myproj",
  "_schemaProject": "http://localhost:8080/v1/projects/myorg/myproj",
  "_rev": 4,
  "_deprecated": true,
  "_createdAt": "2021-04-17T14:54:42.939Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
  "_updatedAt": "2021-04-17T15:02:42.939Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
}

Undeprecate

Unlocks a previously deprecated resource. Further operations can then be performed. The resource will again be found when listing/querying.

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

PUT /v1/resources/{org_label}/{project_label}/{schema_id}/{resource_id}/undeprecate?rev={previous_rev}

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

Example

Request
sourcecurl -X PUT \
     -H "Content-Type: application/json" \
     "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/undeprecate?rev=3"
Response
source{
  "@context": "https://bluebrain.github.io/nexus/contexts/metadata.json",
  "@id": "http://localhost:8080/v1/resources/myorg/myproj/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "@type": "http://localhost:8080/Custom",
  "_incoming": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/incoming",
  "_outgoing": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/outgoing",
  "_self": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resource",
  "_project": "http://localhost:8080/v1/projects/myorg/myproj",
  "_schemaProject": "http://localhost:8080/v1/projects/myorg/myproj",
  "_rev": 5,
  "_deprecated": false,
  "_createdAt": "2021-04-17T14:54:42.939Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
  "_updatedAt": "2021-04-17T15:02:42.939Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
}

Change schema

This operation allows to only change the schema of a resource without providing any payload.

PUT /v1/resources/{org_label}/{project_label}/{schema_id}/{resource_id}/update-schema

Example

Request
sourcecurl -X PUT \
     "http://localhost:8080/v1/resources/myorg/myproj/myNewSchema/myId/update-schema"
Response
source{
  "@context": "https://bluebrain.github.io/nexus/contexts/metadata.json",
  "@id": "http://localhost:8080/v1/resources/myorg/myproj/myId",
  "@type": "http://localhost:8080/Custom",
  "_incoming": "http://localhost:8080/v1/resources/myorg/myproj/myNewSchema/myId/incoming",
  "_outgoing": "http://localhost:8080/v1/resources/myorg/myproj/myNewSchema/myId/outgoing",
  "_self": "http://localhost:8080/v1/resources/myorg/myproj/myNewSchema/myId",
  "_constrainedBy": "http://localhost:8080/v1/resources/myorg/myproj/_/myNewSchema",
  "_project": "http://localhost:8080/v1/projects/myorg/myproj",
  "_schemaProject": "http://localhost:8080/v1/projects/myorg/myproj",
  "_rev": 2,
  "_deprecated": false,
  "_createdAt": "2021-04-17T14:54:42.939Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
  "_updatedAt": "2021-04-17T14:56:42.939Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
}

Fetch

GET /v1/resources/{org_label}/{project_label}/{schema_id}/{resource_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.

The {schema_id} segment allows to pass the resource schema:

  • If _ is provided, the value is ignored
  • If another value is provided, it must match the identifier of the resource schema.

Example

Request
sourcecurl "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/metadata.json",
    {
      "@vocab": "http://localhost:8080/",
      "ex": "http://localhost:8080/"
    }
  ],
  "@id": "http://localhost:8080/v1/resources/myorg/myproj/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "@type": "Custom",
  "bool": false,
  "name": "Alex",
  "number": 24,
  "_incoming": "http://localhost:8080/v1/resources/myorg/myproj/myschema/base:fd8a2b32-170e-44e8-808f-44a8cbbc49b0/incoming",
  "_outgoing": "http://localhost:8080/v1/resources/myorg/myproj/myschema/base:fd8a2b32-170e-44e8-808f-44a8cbbc49b0/outgoing",
  "_self": "http://localhost:8080/v1/resources/myorg/myproj/myschema/base:fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resource",
  "_project": "http://localhost:8080/v1/projects/myorg/myproj",
  "_schemaProject": "http://localhost:8080/v1/projects/myorg/myproj",
  "_rev": 4,
  "_deprecated": true,
  "_createdAt": "2021-04-17T14:54:42.939Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
  "_updatedAt": "2021-04-17T15:02:42.939Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
}

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 resource will be returned.

Fetch original payload

GET /v1/resources/{org_label}/{project_label}/{schema_id}/{resource_id}/source?rev={rev}&tag={tag}&annotate={annotate}

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.
  • {annotate}: Boolean - annotate the response with the resource metadata. This field only applies to standard resources and schemas. This field is optional.

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

If {annotate} is set, the metadata is injected alongside with the original payload where the ones from the original payload take precedence. The context in the original payload is also amended with the metadata context.

Example

Request
sourcecurl "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0?rev=4"
Response
source{
  "@context": {
    "ex": "http://localhost:8080/",
    "@vocab": "http://localhost:8080/"
  },
  "@type": "ex:Custom",
  "name": "Alex",
  "number": 24,
  "bool": false
}

Fetch remote contexts

Returns the remote contexts that have been detected during the JSON-LD resolution for this resource.

These contexts can be:

  • Static contexts that are statically defined in Nexus
  • Project contexts that have been registered by Nexus, in this case the entry also provides the project this context lives and its revision at the time the JSON-LD resolution has been performed
GET /v1/resources/{org_label}/{project_label}/{schema_id}/{resource_id}/remote-contexts?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
sourcecurl "http://localhost:8080/v1/resources/org/proj/_/my-resource/remote-contexts"
Response
source{
  "@context": "https://bluebrain.github.io/nexus/contexts/remote-contexts.json",
  "remoteContexts": [
    {
      "@type": "StaticContextRef",
      "iri": "https://bluebrain.github.io/nexus/contexts/metadata.json"
    },
    {
      "@type": "ProjectContextRef",
      "iri": "https://localhost/nexus/context",
      "resource": {
        "id": "https://localhost/nexus/context",
        "project": "org/proj",
        "rev": 5
      }
    }
  ]
}

Fetch tags

GET /v1/resources/{org_label}/{project_label}/{schema_id}/{resource_id}/tags?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
sourcecurl "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/tags?rev=2"
Response
source{
  "@context": "https://bluebrain.github.io/nexus/contexts/tags.json",
  "tags": [
    {
      "rev": 1,
      "tag": "mytag"
    }
  ]
}

List

There are three available endpoints to list resources in different scopes.

Within a project

GET /v1/resources/{org_label}/{project_label}?from={from}
                                             &size={size}
                                             &locate={locate}
                                             &deprecated={deprecated}
                                             &rev={rev}
                                             &type={type}
                                             &typeOperator={typeOperator}
                                             &createdBy={createdBy}
                                             &createdAt={createdAt}
                                             &updatedBy={updatedBy}
                                             &updatedAt={updatedAt}
                                             &schema={schema}
                                             &q={search}
                                             &sort={sort}
                                             &aggregations={aggregations}

Within an organization

This operation returns only resources from projects defined in the organisation {org_label} and where the caller has the resources/read permission.

GET /v1/resources/{org_label}?from={from}
                             &size={size}
                             &locate={locate}
                             &deprecated={deprecated}
                             &rev={rev}
                             &type={type}
                             &typeOperator={typeOperator}
                             &createdBy={createdBy}
                             &createdAt={createdAt}
                             &updatedBy={updatedBy}
                             &updatedAt={updatedAt}
                             &schema={schema}
                             &q={search}
                             &sort={sort}
                             &aggregations={aggregations}

Within all projects

This operation returns only resources from projects where the caller has the resources/read permission.

GET /v1/resources?from={from}
                 &size={size}
                 &locate={locate}
                 &deprecated={deprecated}
                 &rev={rev}
                 &type={type}
                 &typeOperator={typeOperator}
                 &createdAt={createdAt}
                 &createdBy={createdBy}
                 &updatedAt={updatedAt}
                 &updatedBy={updatedBy}
                 &schema={schema}
                 &q={search}
                 &sort={sort}
                 &aggregations={aggregations}

Parameter description

How to use time ranges

A time range parameter allows to filter resources by their creation date or their last update date.

The provided dates can be:

  • A date following the format YYYY-MM-DDTHH:MM:SSZ
  • A wild card * to express no restriction on a limit

Examples of ranges:

  • 2023-06-08T14:00:00Z..*: Matchers resources created after the June 8, 2023 at 14.00
  • *..2023-06-08T14:00:00Z: Matchers resources created before the June 8, 2023 at 14.00
  • 2023-04-01T00:00:00Z..2023-06-08T14:00:00Z: Matchers resources created between the April 1st at 00.00 and June 8, 2023 at 14.00
  • {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
  • {locate}: Iri - can be used to find a resource by its @id or its address (_self)
  • {deprecated}: Boolean - can be used to filter the resulting resources based on their deprecation status
  • {rev}: Number - can be used to filter the resulting resources based on their revision value
  • {type}: Iri - can be used to filter the resulting resources based on their @type value. This parameter can appear multiple times, filtering further the @type value.
  • {typeOperator}: String (and/or) - used to determine how multiple type values affect the query, either requiring all to match (and) or any to match (or); defaults to or. See De Morgan’s laws for inference rules.
  • {createdBy}: Iri - can be used to filter the resulting resources based on their creator
  • {createdAt}: Time range - can be used to filter the resulting resources based on their creation date
  • {updatedBy}: Iri - can be used to filter the resulting resources based on the person which performed the last update
  • {updatedAt}: Time range - can be used to filter the resulting resources based when was performed the last update
  • {schema}: Iri - can be used to filter the resulting resources based on the conformant schema
  • {search}: String - can be provided to select only the resources in the collection that have attribute values matching (containing) the provided string
  • {sort}: String - can be used to sort resources based on a payloads’ field. This parameter can appear multiple times to enable sorting by multiple fields. The default is done by _createdBy and @id.
  • {aggregations}: Boolean - if true then the response will only contain aggregations of the @type and _project fields; defaults to false. See Aggregations

Example

Request
sourcecurl "http://localhost:8080/v1/resources/myorg/myproj"
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/search-metadata.json"
  ],
  "_total": 1,
  "_results": [
    {
      "@id": "http://localhost:8080/v1/resources/myorg/myproj/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
      "@type": "http://localhost:8080/ustom",
      "_incoming": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/incoming",
      "_outgoing": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/outgoing",
      "_self": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
      "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resource",
      "_project": "http://localhost:8080/v1/projects/myorg/myproj",
      "_schemaProject": "http://localhost:8080/v1/projects/myorg/myproj",
      "_rev": 4,
      "_deprecated": true,
      "_createdAt": "2021-04-17T14:54:42.939Z",
      "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
      "_updatedAt": "2021-04-17T15:02:42.939Z",
      "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
    }
  ],
  "_next": "http://localhost:8080/v1/resources/myorg/myproj?after=%5B1559045718752,%22https://nexus.example.com/v1/resources/myorg/myproj/fd8a2b32-170e-44e8-808f-44a8cbbc49b029%22%5D"
}
Aggregations request
sourcecurl "http://localhost:8080/v1/resources/myorg?aggregations=true"
Aggregations response
source{
  "@context": "https://bluebrain.github.io/nexus/contexts/aggregations.json",
  "aggregations": {
    "projects": {
      "buckets": [
        {
          "doc_count": 5,
          "key": "http://delta:8080/v1/projects/myorg/myproject"
        },
        {
          "doc_count": 5,
          "key": "http://delta:8080/v1/projects/myorg/myproject2"
        }
      ],
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 0
    },
    "types": {
      "buckets": [
        {
          "doc_count": 6,
          "key": "https://bluebrain.github.io/nexus/vocabulary/View"
        },
        {
          "doc_count": 2,
          "key": "https://bluebrain.github.io/nexus/vocabulary/CompositeView"
        },
        {
          "doc_count": 2,
          "key": "https://bluebrain.github.io/nexus/vocabulary/DiskStorage"
        },
        {
          "doc_count": 2,
          "key": "https://bluebrain.github.io/nexus/vocabulary/ElasticSearchView"
        },
        {
          "doc_count": 2,
          "key": "https://bluebrain.github.io/nexus/vocabulary/InProject"
        },
        {
          "doc_count": 2,
          "key": "https://bluebrain.github.io/nexus/vocabulary/Project"
        },
        {
          "doc_count": 2,
          "key": "https://bluebrain.github.io/nexus/vocabulary/Resolver"
        },
        {
          "doc_count": 2,
          "key": "https://bluebrain.github.io/nexus/vocabulary/SparqlView"
        },
        {
          "doc_count": 2,
          "key": "https://bluebrain.github.io/nexus/vocabulary/Storage"
        }
      ],
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 0
    }
  },
  "total": 12
}

Aggregations

Warning

Aggregations are experimental and the API is subject to change.

Adding the aggregations=true query parameter to a list query allows to aggregate the underlying resources by predefined terms. Currently, the following aggregations will be returned:

  • projects: a bucket aggregation of the resources by the project they belong to
  • types: a bucket aggregation of the @types featured in the resources

Aggregation works on the same scopes as listing (all projects, organization, and project), and only aggregates the resources for which the caller has resource/read permission.

List filtering by schema

This operation is only available at the project scope.

Within a project

GET /v1/resources/{org_label}/{project_label}/{schemaId}?from={from}
                                                        &size={size}
                                                        &deprecated={deprecated}
                                                        &rev={rev}&type={type}
                                                        &createdBy={createdBy}
                                                        &updatedBy={updatedBy}
                                                        &aggregations={aggregations}

Parameter description

  • {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 resources based on their deprecation status
  • {rev}: Number - can be used to filter the resulting resources based on their revision value
  • {type}: Iri - can be used to filter the resulting resources 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 resources based on their creator
  • {updatedBy}: Iri - can be used to filter the resulting resources based on the person which performed the last update
  • {aggregations}: Boolean - if true then the response will only contain aggregations of the @type and _project fields; defaults to false. See Aggregations

Example

Request
sourcecurl "http://localhost:8080/v1/resources/myorg/myproj/myschema"
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/search-metadata.json"
  ],
  "_total": 1,
  "_results": [
    {
      "@id": "http://localhost:8080/v1/resources/myorg/myproj/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
      "@type": "http://localhost:8080/ustom",
      "_incoming": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/incoming",
      "_outgoing": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/outgoing",
      "_self": "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
      "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resource",
      "_project": "http://localhost:8080/v1/projects/myorg/myproj",
      "_schemaProject": "http://localhost:8080/v1/projects/myorg/myproj",
      "_rev": 4,
      "_deprecated": true,
      "_createdAt": "2021-04-17T14:54:42.939Z",
      "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
      "_updatedAt": "2021-04-17T15:02:42.939Z",
      "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
    }
  ],
  "_next": "http://localhost:8080/v1/resources/myorg/myproj?after=%5B1559045718752,%22https://nexus.example.com/v1/resources/myorg/myproj/fd8a2b32-170e-44e8-808f-44a8cbbc49b029%22%5D"
}

List incoming links

Provides a list of resources where the current resource {resource_id} is being referenced in the payload.

GET /v1/resources/{org_label}/{project_label}/{schema_id}/{resource_id}/incoming
                  ?from={from}
                  &size={size}

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

Example

Request
sourcecurl "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/incoming"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/metadata.json",
    "https://bluebrain.github.io/nexus/contexts/search.json"
  ],
  "_total": 1,
  "_results": [
    {
      "@id": "https://bluebrain.github.io/nexus/vocabulary/reconstruction1",
      "@type": [
        "http://localhost:8080/v1/vocabs/myorg/myproject/Entity",
        "http://localhost:8080/v1/vocabs/myorg/myproject/Dataset",
        "http://localhost:8080/v1/vocabs/myorg/myproject/ReconstructedPatchedCell"
      ],
      "paths": "http://localhost:8080/v1/vocabs/myorg/myproject/subject",
      "_self": "http://localhost:8080/v1/resources/myorg/myproject/_/nxv:reconstruction1",
      "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/unconstrained.json",
      "_project": "http://localhost:8080/v1/projects/myorg/myproject",
      "_rev": 4,
      "_deprecated": false,
      "_createdAt": "2021-04-28T13:28:00.186Z",
      "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
      "_updatedAt": "2021-04-29T13:41:45.357Z",
      "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
    }
  ]
}

List outgoing links

Provides a list of resources that are being used in the current resource {resource_id} payload. It also offers information 

GET /v1/resources/{org_label}/{project_label}/{schema_id}/{resource_id}/outgoing
                  ?from={from}
                  &size={size}
                  &includeExternalLinks={includeExternalLinks}

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
  • {includeExternalLinks}: Boolean - flag to decide whether or not external links are to be included. External links are references to resources in other projects, or even resources external to Nexus; defaults to true

Example

Request
sourcecurl "http://localhost:8080/v1/resources/myorg/myproj/myschema/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/outgoing?includeExternalLinks=true"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/metadata.json",
    "https://bluebrain.github.io/nexus/contexts/search.json"
  ],
  "_total": 4,
  "_results": [
    {
      "@id": "https://bluebrain.github.io/nexus/vocabulary/mouse1",
      "@type": [
        "http://localhost:8080/v1/vocabs/myorg/myproject/Entity",
        "http://localhost:8080/v1/vocabs/myorg/myproject/Subject"
      ],
      "paths": "http://localhost:8080/v1/vocabs/myorg/myproject/subject",
      "_self": "http://localhost:8080/v1/resources/myorg/nxv:mouse1",
      "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/unconstrained.json",
      "_project": "http://localhost:8080/v1/projects/myorg/myproject",
      "_rev": 1,
      "_deprecated": false,
      "_createdAt": "2021-04-28T13:27:42.707Z",
      "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
      "_updatedAt": "2021-04-28T13:27:42.707Z",
      "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
    },
    {
      "@id": "https://bluebrain.github.io/nexus/vocabulary/jane",
      "@type": [
        "http://localhost:8080/v1/vocabs/myorg/myproject/Agent",
        "http://localhost:8080/v1/vocabs/myorg/myproject/Person"
      ],
      "paths": [
        "http://localhost:8080/v1/vocabs/myorg/myproject/contribution",
        "http://localhost:8080/v1/vocabs/myorg/myproject/agent"
      ],
      "_self": "http://localhost:8080/v1/resources/myorg/myproject/_/nxv:jane",
      "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/unconstrained.json",
      "_project": "http://localhost:8080/v1/projects/myorg/myproject",
      "_rev": 1,
      "_deprecated": false,
      "_createdAt": "2021-04-28T13:26:27.627Z",
      "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
      "_updatedAt": "2021-04-28T13:26:27.627Z",
      "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
    },
    {
      "@id": "http://uri.interlex.org/base/ilx_0383233",
      "@type": "http://localhost:8080/v1/vocabs/myorg/myproject/MType",
      "paths": [
        "http://localhost:8080/v1/vocabs/myorg/myproject/annotation",
        "http://localhost:8080/v1/vocabs/myorg/myproject/hasBody"
      ]
    },
    {
      "@id": "http://purl.obolibrary.org/obo/UBERON_0008933",
      "paths": [
        "http://localhost:8080/v1/vocabs/myorg/myproject/brainLocation",
        "http://localhost:8080/v1/vocabs/myorg/myproject/brainRegion"
      ]
    }
  ]
}

Server Sent Events

GET /v1/resources/events                              # for all resource events in the application
GET /v1/resources/{org_label}/events                  # for resource events in the given organization
GET /v1/resources/{org_label}/{project_label}/events  # for resource events in the given project

The caller must have respectively the events/read permission on /, {org_label} and {org_label}/{project_label}.

  • {org_label}: String - the selected organization for which the events are going to be filtered
  • {project_label}: String - the selected project for which the events are going to be filtered
  • Last-Event-Id: String - optional HTTP Header that identifies the last consumed resource 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 server sent events response contains a series of resource events, represented in the following way

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

where…

  • {payload}: Json - is the actual payload of the current resource
  • {type}: String - is a type identifier for the current resource. Possible types are related to core resource types (Resouce, Schema, Resolver) and available plugin types
  • {id}: String - is the identifier of the resource event. It can be used in the Last-Event-Id query parameter

Example

Request
sourcecurl "http://localhost:8080/v1/resources/events"
Response
sourcedata:{"@context":"https://bluebrain.github.io/nexus/contexts/metadata.json","@type":"ResourceCreated","_resourceId":"http://localhost:8080/v1/resources/myorg/myproject/_/7887416b-d501-4508-a625-2a6664dfca94","_source":{"@type":"Hobbit","age":23,"name":"Frodo"},"_types":["http://localhost:8080/v1/vocabs/myorg/myproject/Hobbit"],"_constrainedBy":"https://bluebrain.github.io/nexus/schemas/unconstrained.json","_project":"http://localhost:8080/v1/projects/myorg/myproject","_schemaProject": "http://localhost:8080/v1/projects/myorg/myproject","_instant":"2021-04-24T07:35:47.447631Z","_rev": 1,"_subject":"http://localhost:8080/v1/realms/github/users/myuser"}
event:ResourceCreated
id:aebbf8f4-9652-11e9-89a7-6d3c5701d287

data:{"@context":"https://bluebrain.github.io/nexus/contexts/metadata.json","@type":"ResourceUpdated","_resourceId":"http://localhost:8080/v1/resources/myorg/myproject/_/7887416b-d501-4508-a625-2a6664dfca94","_source":{"@type":"Hobbit","age":25,"name":"Frodo"},"_types":["http://localhost:8080/v1/vocabs/myorg/myproject/Hobbit"],"_constrainedBy":"https://bluebrain.github.io/nexus/schemas/unconstrained.json","_project":"http://localhost:8080/v1/projects/myorg/myproject", "_schemaProject": "http://localhost:8080/v1/projects/myorg/myproject","_instant":"2021-04-24T07:36:27.130185Z","_rev":2,"_subject":"http://localhost:8080/v1/realms/github/users/myuser"}
event:ResourceUpdated
id:c6642f90-9652-11e9-89a7-6d3c5701d287


data:{"@context":"https://bluebrain.github.io/nexus/contexts/metadata.json","@type":"ResourceTagAdded","_resourceId":"http://localhost:8080/v1/resources/myorg/myproject/_/7887416b-d501-4508-a625-2a6664dfca94","tag":"mytag","targetRev":1,"_types":["http://localhost:8080/v1/vocabs/myorg/myproject/Hobbit"],"_project":"http://localhost:8080/v1/projects/myorg/myproject","_instant":"2021-04-24T07:40:59.2813Z","_project":"http://localhost:8080/v1/projects/myorg/myproject","_rev":3,"_subject":"http://localhost:8080/v1/anonymous"}
event:ResourceTagAdded
id:e024e5f0-9652-11e9-89a7-6d3c5701d287

data:{"@context":"https://bluebrain.github.io/nexus/contexts/metadata.json","@type":"ResourceDeprecated","_resourceId":"http://localhost:8080/v1/resources/myorg/myproject/_/7887416b-d501-4508-a625-2a6664dfca94","_types":["http://localhost:8080/v1/vocabs/myorg/myproject/Hobbit"],"_project":"http://localhost:8080/v1/projects/myorg/myproject","_instant":"2021-04-24T07:45:12.558514Z","_rev":4,"_subject":"http://localhost:8080/v1/realms/github/users/myuser"}
event:ResourceDeprecated
id:ce6549e0-9652-11e9-89a7-6d3c5701d287
v1.11.x