Outdated version

You are browsing the docs for Nexus v1.9.x, the latest release is available here

Id Resolution

Id Resolution allows to resolve a resource by providing only a resource identifier (the @id value of a resource). In case there are multiple resources with the same identifier across different projects, the response provides all choices for disambiguation.

Authorization notes

When performing a request, the caller must have resources/read permission on the project each resource belongs to.

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

Resolve

GET /v1/resolve/{id}

where…

  • {id}: the identifier of the resource to resolve (URL encoded value).

Example

The following example shows how to perform a request and possible responses. If the provided identifier can be resolved uniquely, the response is identical to that of the resource fetch operation. In case there are multiple choices, the response is that of a listing operation that filters for the resource identifier.

Request
sourcecurl "http://localhost:8080/v1/resolve/https%3A%2F%2Fexample.com%2FAlice"
Response (single resource) 
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/metadata.json",
    {
      "@vocab": "https://schema.org/"
    }
  ],
  "@id": "https://example.com/Alice",
  "@type": "Person",
  "name": "Alice",
  "age": 42,
  "_constrainedBy" : "https://bluebrain.github.io/nexus/schemas/unconstrained.json",
  "_createdAt" : "1970-01-01T00:00:00Z",
  "_createdBy" : "http://localhost/v1/anonymous",
  "_deprecated" : false,
  "_incoming" : "http://localhost/v1/resources/myorg/myproject/_/https%3A%2F%2Fexample.com%2FAlice/incoming",
  "_outgoing" : "http://localhost/v1/resources/myorg/myproject/_/https%3A%2F%2Fexample.com%2FAlice/outgoing",
  "_project" : "http://localhost/v1/projects/myorg/myproject",
  "_rev" : 1,
  "_schemaProject" : "http://localhost/v1/projects/myorg/myproject",
  "_self" : "http://localhost/v1/resources/myorg/myproject/_/https%3A%2F%2Fexample.com%2FAlice",
  "_updatedAt" : "1970-01-01T00:00:00Z",
  "_updatedBy" : "http://localhost/v1/anonymous"
}
Response (multiple choices) 
source{
  "@context" : [
    "https://bluebrain.github.io/nexus/contexts/metadata.json",
    "https://bluebrain.github.io/nexus/contexts/search.json"
  ],
  "_total" : 2,
  "_results" : [
    {
      "@id" : "https://example.com/Alice",
      "_constrainedBy" : "https://bluebrain.github.io/nexus/schemas/unconstrained.json",
      "_createdAt" : "2023-09-22T13:55:33.493Z",
      "_createdBy" : "http://localhost:8080/v1/realms/myrealm/users/bob",
      "_deprecated" : false,
      "_incoming" : "http://localhost:8080/v1/resources/myorg/myproject/_/https:%2F%2Fexample.com%2FAlice/incoming",
      "_outgoing" : "http://localhost:8080/v1/resources/myorg/myproject/_/https:%2F%2Fexample.com%2FAlice/outgoing",
      "_project" : "http://localhost:8080/v1/projects/myorg/myproject",
      "_rev" : 1,
      "_schemaProject" : "http://localhost:8080/v1/projects/myorg/myproject",
      "_score" : 0.0,
      "_self" : "http://localhost:8080/v1/resources/myorg/myproject/_/https:%2F%2Fexample.com%2FAlice",
      "_updatedAt" : "2023-09-22T13:55:33.493Z",
      "_updatedBy" : "http://localhost:8080/v1/realms/myrealm/users/bob"
    },
    {
      "@id" : "https://example.com/Alice",
      "_constrainedBy" : "https://bluebrain.github.io/nexus/schemas/unconstrained.json",
      "_createdAt" : "2023-09-22T13:55:33.459Z",
      "_createdBy" : "http://localhost:8080/v1/realms/myrealm/users/bob",
      "_deprecated" : false,
      "_incoming" : "http://localhost:8080/v1/resources/myorg/secondproject/_/https:%2F%2Fexample.com%2FAlice/incoming",
      "_outgoing" : "http://localhost:8080/v1/resources/myorg/secondproject/_/https:%2F%2Fexample.com%2FAlice/outgoing",
      "_project" : "http://localhost:8080/v1/projects/myorg/secondproject",
      "_rev" : 1,
      "_schemaProject" : "http://localhost:8080/v1/projects/myorg/secondproject",
      "_score" : 0.0,
      "_self" : "http://localhost:8080/v1/resources/myorg/secondproject/_/https:%2F%2Fexample.com%2FAlice",
      "_updatedAt" : "2023-09-22T13:55:33.459Z",
      "_updatedBy" : "http://localhost:8080/v1/realms/myrealm/users/bob"
    }
  ],
  "_maxScore" : 0.0
}

Resolve (Proxy Pass)

Note

This endpoint is designed for the Nexus deployment at the Blue Brain Project and as such might not suit the needs of other deployments.

The resolve endpoint offers resource resolution on the resources the caller has access to. As such, if the client is a browser and does not have the ability to include an authorization header in the request, it is possible to use the proxy pass version of the resolve endpoint which will lead the client to a Nexus Fusion authentication page. This will allow to “inject” the user’s token in a subsequent resolve request made by Nexus Fusion.

Configuration

  • app.fusion.base: String - base URL for Nexus Fusion
  • app.fusion.enable-redirects: Boolean - needs to be true in order for redirects to work (defaults to false)
  • app.fusion.resolve-base: String - base URL to use when reconstructing the resource identifier in the proxy pass endpoint

Redirection

  1. The client calls /v1/resolve-proxy-pass/{segment}
  2. Nexus Delta reconstructs the resource identifier
    • {resourceId} = {resolveBase}/{segment}
  3. Nexus Delta redirects the client to…
    • the {fusionBaseUrl}/resolve/{resourceId} Fusion endpoint if the Accept: text/html header is present
    • the /v1/resolve/{resourceId} Delta endpoint otherwise

The Nexus Fusion resolve page allows the user to authenticate (if they are not already authenticated) and will perform a call to the Nexus Delta /v1/resolve/{resourceId} with the user’s authentication token.

All calls to the /v1/resolve-proxy-pass endpoint lead to 303 See Other responses.

Example

The example below assumes that:

  • {fusionBaseUrl} = http://localhost:8080/fusion
  • {segment} = nexus/data/identifier
  • {resolveBase} = https://example.com
Request
sourcecurl "http://localhost:8080/v1/resolve-proxy-pass/nexus/data/identifier"
Redirect (when Acccept:text/html is provided) 
source303 See Other
The response to the request can be found under <a href="http://localhost:8080/fusion/resolve/https:%2F%2Fexample.com%2Fnexus%2Fdata%2Fidentifier">this URI</a> using a
GET method.
Redirect (no Accept:text/html provided) 
source303 See Other
The response to the request can be found under <a href="https://localhost:8080/v1/resolve/https:%2F%2Fexample.com%2Fnexus%2Fdata%2Fidentifier">this URI</a> using a
GET method.

Remark

In your networking setup, if a proxy pass is enabled to map https://example.com/nexus/data/* to https://localhost:8080/v1/resolve-proxy-pass/nexus/data/*, the proxy pass allows to de facto resolve resource with identifier of the type https://example.com/nexus/data/* by simply querying their @id.

v1.9.x