v1 API discrepancies

The API endpoint in v1 starts with the same base (like from v1). So the client should expect to have certain commonalities on the format of the responses. However…

resource created response:

Admin

{
    "@context": "https://bbp-nexus.epfl.ch/staging/v0/contexts/nexus/core/resource/v0.4.0",
    "@id": "http://admin.dev.nexus.ocp.bbp.epfl.ch/v1/projects/bbp/example4",
    "_rev": 1
}

KG

{
    "@context": "https://bluebrain.github.io/nexus/contexts/resource",
    "@id": "nxv:someId",
    "@type": ["nxv:someType"],
    "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/view",
    "_createdAt": "2018-08-23T14:36:40.329Z",
    "_createdBy": "https://bbp-nexus.epfl.ch/v1/realms/bbp-test/users/0745c962-a736-4616-9221-cb0b62c22cf8",
    "_updatedAt": "2018-08-23T18:09:50.473Z",
    "_updatedBy": "https://bbp-nexus.epfl.ch/v1/realms/bbp-test/users/0745c962-a736-4616-9221-cb0b62c22cf8",
    "_rev": 3,
    "_deprecated": false
}

resource fetch response

ADMIN

{
    "@context": "https://bbp-nexus.epfl.ch/staging/v0/contexts/nexus/core/resource/v0.4.0",
    "@id": "http://admin.dev.nexus.ocp.bbp.epfl.ch/v1/projects/bbp/example",
    "@type": "nxv:Project",
    ...
    "_rev": 2,
    "_deprecated": false
}

KG

{
    "@context": [
        "https://bluebrain.github.io/nexus/contexts/view",
        "https://bluebrain.github.io/nexus/contexts/resource"
    ],
    "@id": "nxv:someId",
    "@type": [ "nxv:someType" ],
    ...
    "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/view",
    "_createdAt": "2018-08-23T14:36:40.329Z",
    "_createdBy": "http://iam.dev.nexus.ocp.bbp.epfl.ch/v1/realms/bbp-test/users/0745c962-a736-4616-9221-cb0b62c22cf8",
    "_updatedAt": "2018-08-23T16:34:47.143Z",
    "_updatedBy": "http://iam.dev.nexus.ocp.bbp.epfl.ch/v1/realms/bbp-test/users/0745c962-a736-4616-9221-cb0b62c22cf8",
    "_rev": 2,
    "_deprecated": false
}

resource list response

ADMIN

{
    "@context": "http://admin.dev.nexus.ocp.bbp.epfl.ch/v1/contexts/nexus/core/search/v0.1.0",
    "_results": [
        {
            "_id": "http://admin.dev.nexus.ocp.bbp.epfl.ch/v1/projects/01pkyhg5n5raht2/xo04q2x8q2ml20t",
            "_source": {
                "@id": "http://admin.dev.nexus.ocp.bbp.epfl.ch/v1/projects/01pkyhg5n5raht2/xo04q2x8q2ml20t"
            }
        },
        {
            "_id": "http://admin.dev.nexus.ocp.bbp.epfl.ch/v1/projects/07e2ort0jydqqba/rjuq67rh63ynuyl",
            "_source": {
                "@id": "http://admin.dev.nexus.ocp.bbp.epfl.ch/v1/projects/07e2ort0jydqqba/rjuq67rh63ynuyl"
            }
        }
    ],
    "_total": 2,
    "_links": {
        "_next": "http://admin.dev.nexus.ocp.bbp.epfl.ch/v1/projects?from=50&size=50",
        "_self": "http://admin.dev.nexus.ocp.bbp.epfl.ch/v1/projects"
    }
}

KG

{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/search",
    "https://bluebrain.github.io/nexus/contexts/resource"
  ],
  "total": 3,
  "results": [
    {
      "resultId": "http://nexus.com/result1"
    },
    {
      "resultId": "http://nexus.com/result2"
    },
    {
      "resultId": "http://nexus.com/result3"
    }
  ]
}

Even though the API seems mostly consistent in terms of URI, path and query params, from the json payload perspective it isn’t at all. We have to make some decision on what to choose. From my side, few notes:

• I’d get rid of links at all and directly add the fields we are interested in as metadata (like _constrainedBy in kg).
• I would replace _self by accessId (is more explicit).

[genric]

I suggest adding @type in the result set, something like _resultType. As if you just want to use that instance to make a link you need to retrieve the whole entity to get it’s type.

[bogdanromanx]

I kind of prefer _self over _accessId; the term access id is something we’ve used to avoid confusion when taking about ids; but its value is not an id but merely a resource address. I think self is well understood by clients.

What if we have something like this for listings with future filtering (notice the additional scoring fields for full text search)?

{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/search",
    "https://bluebrain.github.io/nexus/contexts/resource"
  ],
  "_maxScore": 42,
  "_total": 1,
  "_results": [
    {
      "@id": "http://nexus.com/result1",
      "@type": [
        "http://example.com/Example",
        "http://www.w3.org/ns/prov#Entity"
      ],
      "_score": 42,
      "_self": "http://nexus.com/{org}/{proj}/{schema}/{id}",
      "_constrainedBy": "http://nexus.com/myschema",
      "_createdAt": "2018-08-23T14:36:40.329Z",
      "_createdBy": "http://iam.dev.nexus.ocp.bbp.epfl.ch/v1/realms/bbp-test/users/0745c962-a736-4616-9221-cb0b62c22cf8",
      "_updatedAt": "2018-08-23T16:34:47.143Z",
      "_updatedBy": "http://iam.dev.nexus.ocp.bbp.epfl.ch/v1/realms/bbp-test/users/0745c962-a736-4616-9221-cb0b62c22cf8",
      "_rev": 1,
      "_deprecated": false
    }
  ]
}

and if we want to include the complete resource, we can have:

{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/search",
    "https://bluebrain.github.io/nexus/contexts/resource"
  ],
  "_maxScore": 42,
  "_total": 1,
  "_results": [
    {
      "@context": "http://nexus.com/result1context",
      "@id": "http://nexus.com/result1",
      "@type": ["Example", "prov:Entity"],
      "schema:name": "This is the Result 1",
      "_score": 42,
      "_self": "http://nexus.com/{org}/{proj}/{schema}/{id}",
      "_createdAt": "2018-08-23T14:36:40.329Z",
      "_createdBy": "http://iam.dev.nexus.ocp.bbp.epfl.ch/v1/realms/bbp-test/users/0745c962-a736-4616-9221-cb0b62c22cf8",
      "_updatedAt": "2018-08-23T16:34:47.143Z",
      "_updatedBy": "http://iam.dev.nexus.ocp.bbp.epfl.ch/v1/realms/bbp-test/users/0745c962-a736-4616-9221-cb0b62c22cf8",
      "_constrainedBy": "http://nexus.com/myschema"
      "_rev": 1
      "_deprecated": false
    }
  ]
}

Thoughts?

Edited: changed types to full iris when lacking context.