Snapshot version

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

Resolvers

Resolvers are rooted in the /v1/resolvers/{org_label}/{project_label} collection and are used in the following scenarios:

Bring the content of the owl:imports predicate for schema resources. The value is the @id of the resource. E.g.: You can define owl imports on a schema, as follows "owl:imports": "http://example.com/myid". The resolver will try to find a resource with "@id": "http://example.com/myid" and if found, will bring the payload into the original resource.
Bring the content of the @context links. The value is the @id of the resource. E.g.: A resource might define the context as follows: "@context": "http://example.com/id". The resolver will try to find a resource with "@id": "http://example.com/id" and if found, will bring the payload into the original resource.

Each resolver belongs to a project identifier by the label {project_label} inside an organization identifier by the label {org_label}.

Authorization notes

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

When reading resolvers, 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.

Resolver types

There are several types of resolvers, which perform resolution in different scopes.

InProject resolver

The scope of the resolution is the current project where the resource resides. In other words:

Schema A can import schema B using the owl:imports as long as schema B is located on the same project as schema A.
Resource A can reference to a remote context existing in resource B as long as resource B is located on the same project as resource A.

This resolver gets automatically created when the project is created and has the highest priority for resolution. It should not be modified.

InProject resolver payload

{
    "@id": "https://bluebrain.github.io/nexus/vocabulary/defaultInProject",
    "@type": "InProject",
    "priority": {priority},
}

where {priority} is a numeric value (from 0 - 1000) which defines the resolution priority when attempting to find the resource with a particular @id.

CrossProject resolver

The scope of the resolution is the collections of projects P defined on the resolver. CrossProject resolution also defines a identity policy I (via the identities or the useCurrentCaller fields) to enforce ACLs. In other words:

Schema A can import schema B using the owl:imports as long as schema B is located in some of the projects from the collection P and as long I have resources/read permissions on the schema B project.
Resource A can reference to a remote context existing in resource B as long as resource B is located in some of the projects from the collection P and as long as I have resources/read permissions on the schema B project.

CrossProject resolver payload

{
  "@id": "{someId}",
  "@type": ["Resolver", "CrossProject"],
  "priority": {priority}
  "resourceTypes": ["{resourceType}", ...],
  "projects": ["{project}", ... ],
  "identities": [ {identity}, {...} ],
  "useCurrentCaller": {useCurrentCaller},
}

where…

{someId}: Iri - the @id value for this resolver.
{priority}: Number - value (from 0 - 1000) which defines the resolution priority when attempting to find the resource. All resolvers must have a different priority in a same project
{resourceType}: Iri - resolves only the resources with @type containing {resourceType}. This field is optional. with a particular @id.
{project}: String - the user friendly reference to the project from where the resolution process will attempt to find the @id’s. It follows the format {organization}/{project}.
{identity}: Json object - the identity against which to enforce ACLs during resolution process. Can’t be defined if useCurrentCaller is set to true
{useCurrentCaller}: Boolean - the resolution process will use the caller and its identitites to enforce acls. Can’t be true when _identity_ is defined.

Create using POST

POST /v1/resolvers/{org_label}/{project_label}
  {...}

The json payload:

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

Example

Request

sourcecurl -X POST \
     -H "Content-Type: application/json" \
     "http://localhost:8080/v1/resolvers/myorg/myproj" \
     -d \
'{
  "@id": "https://bluebrain.github.io/nexus/vocabulary/myresolver",
  "@type": "CrossProject",
  "projects": [
    "org1/project1",
    "org1/project2"
  ],
  "identities": [
    {
      "realm": "myrealm",
      "subject": "name"
    }
  ],
  "priority": 50
}'

Payload

source{
  "@id": "https://bluebrain.github.io/nexus/vocabulary/myresolver",
  "@type": [
    "CrossProject"
  ],
  "projects": [
    "org1/project1",
    "org1/project2"
  ],
  "identities": [
    {
      "realm": "myrealm",
      "subject": "name"
    }
  ],
  "priority": 50
}

Response

source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/resolvers-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "https://bluebrain.github.io/nexus/vocabulary/myresolver",
  "@type": [
    "Resolver",
    "CrossProject"
  ],
  "_self": "http://localhost:8080/v1/resolvers/myorg/myproject/nxv:myresolver",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resolvers",
  "_project": "myorg/myproj",
  "_rev": 1,
  "_deprecated": false,
  "_createdAt": "2021-04-18T09:58:00.801Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
  "_updatedAt": "2021-04-18T09:58:00.801Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
}

Create using PUT

This alternative endpoint to create a resolver 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/resolvers/{org_label}/{project_label}/{resolver_id}
  {...}

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

Example

Request

sourcecurl -X PUT \
     -H "Content-Type: application/json" \
     "http://localhost:8080/v1/resolvers/myorg/myproj/nxv:myresolver" \
     -d \
'{
  "@type": "CrossProject",
  "projects": [
    "org1/project1",
    "org1/project2"
  ],
  "useCurrentCaller": true,
  "priority": 50
}'

Payload

source{
  "@id": "https://bluebrain.github.io/nexus/vocabulary/myresolver",
  "@type": [
    "CrossProject"
  ],
  "projects": [
    "org1/project1",
    "org1/project2"
  ],
  "identities": [
    {
      "realm": "myrealm",
      "subject": "name"
    }
  ],
  "priority": 50
}

Response

source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/resolvers-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "https://bluebrain.github.io/nexus/vocabulary/myresolver",
  "@type": [
    "Resolver",
    "CrossProject"
  ],
  "_self": "http://localhost:8080/v1/resolvers/myorg/myproject/nxv:myresolver",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resolvers",
  "_project": "myorg/myproj",
  "_rev": 1,
  "_deprecated": false,
  "_createdAt": "2021-04-18T09:58:00.801Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
  "_updatedAt": "2021-04-18T09:58:00.801Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
}

Update

This operation overrides the payload.

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

PUT /v1/resolvers/{org_label}/{project_label}/{resolver_id}?rev={previous_rev}
  {...}

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

Example

Request

sourcecurl -X PUT \
     -H "Content-Type: application/json" \
     "http://localhost:8080/v1/resolvers/myorg/myproj/nxv:myresolver?rev=1" \
     -d \
'{
  "@type": "CrossProject",
  "projects": [
    "org1/project1",
    "org1/project2"
  ],
  "identities": [
    {
      "realm": "myrealm",
      "subject": "name"
    }
  ],
  "priority": 50
}'

Payload

source{
  "@id": "https://bluebrain.github.io/nexus/vocabulary/myresolver",
  "@type": [
    "CrossProject"
  ],
  "projects": [
    "org1/project1",
    "org1/project2"
  ],
  "identities": [
    {
      "realm": "myrealm",
      "subject": "name"
    }
  ],
  "priority": 50
}

Response

source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/resolvers-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "https://bluebrain.github.io/nexus/vocabulary/myresolver",
  "@type": [
    "Resolver",
    "CrossProject"
  ],
  "_self": "http://localhost:8080/v1/resolvers/myorg/myproject/nxv:myresolver",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resolvers",
  "_project": "myorg/myproj",
  "_rev": 2,
  "_deprecated": false,
  "_createdAt": "2021-04-18T09:58:00.801Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
  "_updatedAt": "2021-04-18T10:10:00.801Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
}

Deprecate

Locks the resolver, so no further operations can be performed. It will also not be taken into account in the resolution process.

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

DELETE /v1/resolvers/{org_label}/{project_label}/{resolver_id}?rev={previous_rev}

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

Example

Request

sourcecurl -X DELETE \
     "http://localhost:8080/v1/resolvers/myorg/myproj/nxv:myresolver?rev=3"

Response

source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/resolvers-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "https://bluebrain.github.io/nexus/vocabulary/myresolver",
  "@type": [
    "Resolver",
    "CrossProject"
  ],
  "_self": "http://localhost:8080/v1/resolvers/myorg/myproject/nxv:myresolver",
  "_constrainedBy" : "https://bluebrain.github.io/nexus/schemas/resolvers.json",
  "_project": "myorg/myproj",
  "_rev": 4,
  "_deprecated": true,
  "_createdAt": "2021-04-18T09:58:00.801Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
  "_updatedAt": "2021-04-18T10:25:00.801Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
}

Fetch

GET /v1/resolvers/{org_label}/{project_label}/{resolver_id}?rev={rev}

where …

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

Example

Request

sourcecurl "http://localhost:8080/v1/resolvers/myorg/myproj/nxv:myresolver"

Response

source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/resolvers-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "https://bluebrain.github.io/nexus/vocabulary/myresolver",
  "@type": [
    "Resolver",
    "CrossProject"
  ],
  "projects": [
    "org1/project1",
    "org1/project2"
  ],
  "identities": [
    {
      "@type": "User",
      "realm": "myrealm",
      "subject": "name"
    }
  ],
  "priority": 50,
  "_self": "http://localhost:8080/v1/resolvers/myorg/myproject/nxv:myresolver",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resolvers",
  "_project": "myorg/myproj",
  "_rev": 4,
  "_deprecated": true,
  "_createdAt": "2021-04-18T09:58:00.801Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
  "_updatedAt": "2021-04-18T10:25:00.801Z",
  "_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/resolvers/{org_label}/{project_label}/{resolver_id}/source?rev={rev}

where …

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

Example

Request

sourcecurl "http://localhost:8080/v1/resolvers/myorg/myproj/nxv:myresolver/source

Response

source{
  "@id": "https://bluebrain.github.io/nexus/vocabulary/myresolver",
  "@type": [
    "CrossProject"
  ],
  "projects": [
    "org1/project1",
    "org1/project2"
  ],
  "identities": [
    {
      "realm": "myrealm",
      "subject": "name"
    }
  ],
  "priority": 50
}

List

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

GET /v1/resolvers/{org_label}/{project_label}

Example

Request

sourcecurl "http://localhost:8080/v1/resolvers/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/resolvers.json"
  ],
  "_total": 2,
  "_results": [
    {
      "@id": "https://bluebrain.github.io/nexus/vocabulary/InProject",
      "@type": [
        "https://bluebrain.github.io/nexus/vocabulary/Resolver",
        "https://bluebrain.github.io/nexus/vocabulary/InProject"
      ],
      "_self": "http://localhost:8080/v1/resolvers/myorg/myproject/nxv:defaultInProject",
      "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resolver",
      "_project": "myorg/myproj",
      "_createdAt": "2021-04-18T09:50:00.801Z",
      "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
      "_updatedAt": "2021-04-18T10:00:00.801Z",
      "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john",
      "_rev": 1,
      "_deprecated": true
    },
    {
      "@id": "https://bluebrain.github.io/nexus/vocabulary/myresolver",
      "@type": [
        "https://bluebrain.github.io/nexus/vocabulary/Resolver",
        "https://bluebrain.github.io/nexus/vocabulary/CrossProject"
      ],
      "_self": "http://localhost:8080/v1/resolvers/myorg/myproject/nxv:myresolver",
      "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resolver",
      "_project": "myorg/myproj",
      "_createdAt": "2021-09-18T09:58:00.801Z",
      "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
      "_updatedAt": "2018-09-18T10:25:00.801Z",
      "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john",
      "_rev": 4,
      "_deprecated": true
    }
  ],
  "_next": "http://localhost:8080/v1/resolvers/myorg/myproj?after=%5B1559045718752,%22https://bluebrain.github.io/nexus/vocabulary/myresolver29%22%5D"
}

Fetch resource using resolvers

Fetches a resource using the provided resolver.

If the resolver segment ({resolver_id}) is _ the resource is fetched from the first resolver in the requested project ({org_label}/{project_label}). The resolvers are ordered by its priority field.

GET /v1/resolvers/{org_label}/{project_label}/{resolver_id}/{resource_id}?rev={rev}
                                                                         &tag={tag}
                                                                         &showReport={showReport}

… where

{resource_id}: Iri - the @id value of the resource to be retrieved.
{rev}: Number - the targeted resource revision to be fetched. This field is optional and defaults to the latest revision.
{tag}: String - the targeted resource tag to be fetched. This field is optional.
{showReport}: Boolean - return the resolver resolution steps instead of the resource for debugging purposes.

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

Example

Request

sourcecurl "http://localhost:8080/v1/resolvers/myorg/myproj/nxv:myresolver/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,
  "_self": "http://localhost:8080/v1/resources/myorg/myproj/myschema/base:fd8a2b32-170e-44e8-808f-44a8cbbc49b0",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/resource",
  "_project": "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"
}

Fetch original resource payload using resolvers

Fetches the original source payload of a resource using the provided resolver.

If the resolver segment ({resolver_id}) is _ the resource is fetched from the first resolver in the requested project ({org_label}/{project_label}). The resolvers are ordered by its priority field.

GET /v1/resolvers/{org_label}/{project_label}/{resolver_id}/{resource_id}/source?rev={rev}&tag={tag}&annotate={annotate}

where … - {resource_id}: Iri - the @id value of the resource to be retrieved. - {rev}: Number - the targeted resource revision to be fetched. This field is optional and defaults to the latest revision. - {tag}: String - the targeted resource tag to be fetched. This field is optional. - {annotate}: Boolean - annotate the response with the resource metadata. This field only applies to standard resources. 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/resolvers/myorg/myproj/nxv:myresolver/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/source"

Response

source{
  "@context": {
    "ex": "http://localhost:8080/",
    "@vocab": "http://localhost:8080/"
  },
  "@type": "ex:Custom",
  "name": "Alex",
  "number": 24,
  "bool": false
}

Server Sent Events

From Delta 1.5, it is possible to fetch SSEs for all resolvers or just resolvers in the scope of an organization or a project.

GET /v1/resolvers/events # for all resolver events in the application
GET /v1/resolvers/{org_label}/events # for resolver events in the given organization
GET /v1/resolvers/{org_label}/{project_label}/events # for resolver 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.

Note

The event type for resolvers SSEs have been changed so that it is easier to distinguish them from other types of resources.

Example

Request

sourcecurl "https://localhost:8080/v1/resolvers/events"

Response

sourcedata:{"@context":["https://bluebrain.github.io/nexus/contexts/metadata.json","https://bluebrain.github.io/nexus/contexts/resolvers.json"],"@type":"ResolverCreated","_constrainedBy":"https://bluebrain.github.io/nexus/schemas/resolvers.json","_instant":"2021-04-18T09:58:00.801Z","_project":"org/project2","_resolverId":"https://bluebrain.github.io/nexus/vocabulary/cross-project","_resourceId":"https://bluebrain.github.io/nexus/vocabulary/cross-project","_rev":1,"_source":{"@context":{"nxv":"https://bluebrain.github.io/nexus/vocabulary/"},"@id":"https://bluebrain.github.io/nexus/vocabulary/cross-project-provided-entities-put2","@type":["CrossProject"],"identities":[{"@type":"User","realm":"wonderland","subject":"alice"}],"priority":9,"projects":["org/project1","org/project2"],"resourceTypes":["nxv:Schema","nxv:Custom"]},"_subject":"http://localhost:8080/v1/realms/wonderland/users/alice","_types":["https://bluebrain.github.io/nexus/vocabulary/Resolver","https://bluebrain.github.io/nexus/vocabulary/CrossProject"]}
event:ResolverCreated
id:1

data:{"@context":["https://bluebrain.github.io/nexus/contexts/metadata.json","https://bluebrain.github.io/nexus/contexts/resolvers.json"],"@type":"ResolverUpdated","_constrainedBy":"https://bluebrain.github.io/nexus/schemas/resolvers.json","_instant":"2021-04-19T09:58:00.801Z","_project":"org/project","_resolverId":"https://bluebrain.github.io/nexus/vocabulary/cross-project","_resourceId":"https://bluebrain.github.io/nexus/vocabulary/cross-project","_rev":2,"_source":{"@type":["InProject"],"priority":34},"_subject":"http://localhost:8080/v1/realms/wonderland/users/bob","_types":["https://bluebrain.github.io/nexus/vocabulary/Resolver","https://bluebrain.github.io/nexus/vocabulary/CrossProject"]}
event:ResolverUpdated
id:2

data:{"@context":["https://bluebrain.github.io/nexus/contexts/metadata.json","https://bluebrain.github.io/nexus/contexts/resolvers.json"],"@type":"ResolverTagAdded","tag":"my-tag","targetRev":1,"_constrainedBy":"https://bluebrain.github.io/nexus/schemas/resolvers.json","_instant":"2021-04-20T09:58:00.801Z","_project":"org/project","_resolverId":"https://bluebrain.github.io/nexus/vocabulary/cross-project","_resourceId":"https://bluebrain.github.io/nexus/vocabulary/cross-project","_rev":3,"_subject":"http://localhost:8080/v1/realms/wonderland/users/alice","_types":["https://bluebrain.github.io/nexus/vocabulary/Resolver","https://bluebrain.github.io/nexus/vocabulary/CrossProject"]}
event:ResolverTagAdded
id:3

data:{"@context":["https://bluebrain.github.io/nexus/contexts/metadata.json","https://bluebrain.github.io/nexus/contexts/resolvers.json"],"@type":"ResolverDeprecated","_constrainedBy":"https://bluebrain.github.io/nexus/schemas/resolvers.json","_instant":"2021-04-21T09:58:00.801Z","_project":"org/project","_resolverId":"https://bluebrain.github.io/nexus/vocabulary/cross-project","_resourceId":"https://bluebrain.github.io/nexus/vocabulary/cross-project","_rev":4,"_subject":"http://localhost:8080/v1/realms/wonderland/users/alice","_types":["https://bluebrain.github.io/nexus/vocabulary/Resolver","https://bluebrain.github.io/nexus/vocabulary/CrossProject"]}
event:ResolverDeprecated
id:6

Edit this page

Snapshot