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.

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

Create a resource using POST

POST /v1/resources/{org_label}/{project_label}/{schema_id}
  {...}

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 -H "Content-Type: application/json" "https://nexus.example.com/v1/resources/myorg/myproj/myschema" -d \
'{
  "@context": {
    "ex": "http://example.com/",
    "@vocab": "http://example.com/"
  },
  "@type": "ex:Custom",
  "name": "Alex",
  "number": 24,
  "bool": false
}'
Full source at GitHub
Payload
{
  "@context": {
    "ex": "http://example.com/",
    "@vocab": "http://example.com/"
  },
  "@type": "ex:Custom",
  "name": "Alex",
  "number": 24,
  "bool": false
}
Full source at GitHub
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "https://nexus.example.com/v1/resources/myorg/myproj/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "@type": "http://example.com/Custom",
  "_self": "https://nexus.example.com/v1/resources/myorg/myproj/myschema/base:fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resource",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 1,
  "_deprecated": false,
  "_createdAt": "2018-09-17T14:54:42.939Z",
  "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
  "_updatedAt": "2018-09-17T14:54:42.939Z",
  "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
}
Full source at GitHub

Create a resource 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}
  {...}

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

Example

Request
curl -XPUT -H "Content-Type: application/json" "https://nexus.example.com/v1/resources/myorg/myproj/myschema/base:fd8a2b32-170e-44e8-808f-44a8cbbc49b0" -d \
'{
  "@context": {
    "ex": "http://example.com/",
    "@vocab": "http://example.com/"
  },
  "@type": "ex:Custom",
  "name": "Alex",
  "number": 24,
  "bool": false
}'
Full source at GitHub
Payload
{
  "@context": {
    "ex": "http://example.com/",
    "@vocab": "http://example.com/"
  },
  "@type": "ex:Custom",
  "name": "Alex",
  "number": 24,
  "bool": false
}
Full source at GitHub
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "https://nexus.example.com/v1/resources/myorg/myproj/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "@type": "http://example.com/Custom",
  "_self": "https://nexus.example.com/v1/resources/myorg/myproj/myschema/base:fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resource",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 1,
  "_deprecated": false,
  "_createdAt": "2018-09-17T14:54:42.939Z",
  "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
  "_updatedAt": "2018-09-17T14:54:42.939Z",
  "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
}
Full source at GitHub

Update a 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}
  {...}

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

Example

Request
curl -XPUT -H "Content-Type: application/json" "https://nexus.example.com/v1/resources/myorg/myproj/myschema/base:fd8a2b32-170e-44e8-808f-44a8cbbc49b0?rev=1" -d \
'{
  "@context": {
    "ex": "http://example.com/",
    "@vocab": "http://example.com/"
  },
  "@type": "ex:Custom",
  "name": "Alex",
  "number": 24,
  "bool": false
}'
Full source at GitHub
Payload
{
  "@context": {
    "ex": "http://example.com/",
    "@vocab": "http://example.com/"
  },
  "@type": "ex:Custom",
  "name": "Alex",
  "number": 24,
  "bool": false
}
Full source at GitHub
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "https://nexus.example.com/v1/resources/myorg/myproj/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "@type": "http://example.com/Custom",
  "_self": "https://nexus.example.com/v1/resources/myorg/myproj/myschema/base:fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resource",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 2,
  "_deprecated": false,
  "_createdAt": "2018-09-17T14:54:42.939Z",
  "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
  "_updatedAt": "2018-09-17T14:56:42.939Z",
  "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
}
Full source at GitHub

Tag a resource

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
curl -XPOST -H "Content-Type: application/json" "https://nexus.example.com/v1/resources/myorg/myproj/myschema/base:fd8a2b32-170e-44e8-808f-44a8cbbc49b0/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": "https://nexus.example.com/v1/resources/myorg/myproj/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "@type": "http://example.com/Custom",
  "_self": "https://nexus.example.com/v1/resources/myorg/myproj/myschema/base:fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resource",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 3,
  "_deprecated": false,
  "_createdAt": "2018-09-17T14:54:42.939Z",
  "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
  "_updatedAt": "2018-09-17T14:58:42.939Z",
  "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
}
Full source at GitHub

Deprecate a resource

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
curl -XDELETE -H "Content-Type: application/json" "https://nexus.example.com/v1/resources/myorg/myproj/myschema/base:fd8a2b32-170e-44e8-808f-44a8cbbc49b0?rev=5"
Full source at GitHub
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "https://nexus.example.com/v1/resources/myorg/myproj/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "@type": "http://example.com/Custom",
  "_self": "https://nexus.example.com/v1/resources/myorg/myproj/myschema/base:fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resource",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 6,
  "_deprecated": true,
  "_createdAt": "2018-09-17T14:54:42.939Z",
  "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
  "_updatedAt": "2018-09-17T15:02:42.939Z",
  "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
}
Full source at GitHub

Fetch a resource (current version)

GET /v1/resources/{org_label}/{project_label}/{schema_id}/{resource_id}

Example

Request
curl "https://nexus.example.com/v1/resources/myorg/myproj/myschema/base:fd8a2b32-170e-44e8-808f-44a8cbbc49b0"
Full source at GitHub
Response
{
  "@context": [
    {
      "@vocab": "http://example.com/",
      "ex": "http://example.com/"
    },
    "https://bluebrain.github.io/nexus/contexts/resource.json"
  ],
  "@id": "https://nexus.example.com/v1/resources/myorg/myproj/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "@type": "Custom",
  "bool": false,
  "name": "Alex",
  "number": 24,
  "_self": "https://nexus.example.com/v1/resources/myorg/myproj/myschema/base:fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resource",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 4,
  "_deprecated": true,
  "_createdAt": "2018-09-17T14:54:42.939Z",
  "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
  "_updatedAt": "2018-09-17T15:02:42.939Z",
  "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
}
Full source at GitHub

Fetch a resource (specific version)

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

… where {rev} is the revision number of the resource to be retrieved.

Example

Request
curl "https://nexus.example.com/v1/resources/myorg/myproj/myschema/base:fd8a2b32-170e-44e8-808f-44a8cbbc49b0?rev=4"
Full source at GitHub
Response
{
  "@context": [
    {
      "@vocab": "http://example.com/",
      "ex": "http://example.com/"
    },
    "https://bluebrain.github.io/nexus/contexts/resource.json"
  ],
  "@id": "https://nexus.example.com/v1/resources/myorg/myproj/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "@type": "Custom",
  "bool": false,
  "name": "Alex",
  "number": 24,
  "_self": "https://nexus.example.com/v1/resources/myorg/myproj/myschema/base:fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resource",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 4,
  "_deprecated": true,
  "_createdAt": "2018-09-17T14:54:42.939Z",
  "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
  "_updatedAt": "2018-09-17T15:02:42.939Z",
  "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
}
Full source at GitHub

Fetch a resource (specific tag)

GET /v1/resources/{org_label}/{project_label}/{schema_id}/{resource_id}?tag={tag}

… where {tag} is the tag of the resource to be retrieved.

Example

Request
curl "https://nexus.example.com/v1/resources/myorg/myproj/myschema/base:fd8a2b32-170e-44e8-808f-44a8cbbc49b0?tag=mytag"
Full source at GitHub
Response
{
  "@context": [
    {
      "@vocab": "http://example.com/",
      "ex": "http://example.com/"
    },
    "https://bluebrain.github.io/nexus/contexts/resource.json"
  ],
  "@id": "https://nexus.example.com/v1/resources/myorg/myproj/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "@type": "Custom",
  "_self": "https://nexus.example.com/v1/resources/myorg/myproj/myschema/base:fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resource",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 1,
  "_deprecated": false,
  "_createdAt": "2018-09-17T14:54:42.939Z",
  "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
  "_updatedAt": "2018-09-17T14:54:42.939Z",
  "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
}
Full source at GitHub

List resources

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

where…

  • {full_text_search_query}: String - can be provided to select only the resources in the collection that have attribute values matching (containing) the provided token; when this field is provided the results will also include score values for each result
  • {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
  • {schema}: Iri - can be used to filter the resulting resources based on the conformant schema

Example

Request
curl "https://nexus.example.com/v1/resources/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": 1,
  "_results": [
    {
      "@id": "https://nexus.example.com/v1/resources/myorg/myproj/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
      "@type": "http://example.com/Custom",
      "_self": "https://nexus.example.com/v1/resources/myorg/myproj/myschema/base:fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
      "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resource",
      "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
      "_rev": 4,
      "_deprecated": true,
      "_createdAt": "2018-09-17T14:54:42.939Z",
      "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
      "_updatedAt": "2018-09-17T15:02:42.939Z",
      "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
    }
  ]
}
Full source at GitHub

List resources belonging to a schema

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

where…

  • {full_text_search_query}: String - can be provided to select only the resources in the collection that have attribute values matching (containing) the provided token; when this field is provided the results will also include score values for each result
  • {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

Example

Request
curl "https://nexus.example.com/v1/resources/myorg/myproj/myschema"
Full source at GitHub
Response
{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/search.json",
    "https://bluebrain.github.io/nexus/contexts/resource.json"
  ],
  "_total": 1,
  "_results": [
    {
      "@id": "https://nexus.example.com/v1/resources/myorg/myproj/fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
      "@type": "http://example.com/Custom",
      "_self": "https://nexus.example.com/v1/resources/myorg/myproj/myschema/base:fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
      "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resource",
      "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
      "_rev": 4,
      "_deprecated": true,
      "_createdAt": "2018-09-17T14:54:42.939Z",
      "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
      "_updatedAt": "2018-09-17T15:02:42.939Z",
      "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
    }
  ]
}
Full source at GitHub