OpenAPI HATEOAS linking

[rduyme]

We validated the update of the OpenAPI with defined API links in https://docs.google.com/document/d/12VOXrgpISSXsIVZtGZ_3zbNIZkTQy4hpMYXI04MtFVQ/edit?tab=t.0#heading=h.3brndhbrt82y

Silvio requested to have these links separated from the core entities model in the meta section.

Here is proposition for an evolution of the meta section. I had to put it in the @graph to have compatible triple.
Note that it is still possible to have embedded approach in product-cc. It produces the same triples.

The main change was to add an as:items to have all the links information in the meta which is already an as:CollectionPage in the current OpenAPI api context (https://skg-if.github.io/api/openapi/ver/1.0.0/context/skg-if-api.json)

We will add new aliases in the skg-if-api.json

-- EXISTING aliases in  https://skg-if.github.io/api/openapi/ver/1.0.0/context/skg-if-api.json
"search_result_page": "as:CollectionPage"
"search_result":"as:Collection"
"part_of": "as:partOf"
 "total_items": "as:totalItems"
 "next_page":"as:next"
  "first_page":"as:first" 
"last_page": "as:last"
 "prev_page":"as:prev"
-- NEW aliases
"link": "as:Link",
 "rel": "as:rel",
 "href": "as:href",
 "result_api_links": "as:items",
 "entity_api_links": "as:url",

Here is the raw not aliased version.

{
  "@context": [
    "https://w3id.org/skg-if/context/1.1.0/skg-if.json",
    {
      "as": "http://www.w3.org/ns/activitystreams#",
      "meta": "@nest",
      "results": "@set"
    }
    ],
  "@graph" : [
    {
      "meta": {
        "@id": "https://cessda.com/skg-if/api/products?filter=product_type:literature&page=1",
     	"@type": "as:CollectionPage",
      	"as:next": {
            "local_identifier": "https://cessda.com/skg-if/api/products?filter=product_type:literature&page=2",
            "@type": "as:CollectionPage"
          },
      	 "as:partOf": {
            "local_identifier": "https://cessda.com/skg-if/api/products?filter=product_type:literature",
            "@type": "as:Collection",
          	"as:totalItems": 54231
          },
          "as:items" : [
          {
              "@id": "https://w3id.org/cessda/product-aaa",
              "as:url": {
                "@type": "as:Link",
                "as:rel": "self",
                "as:href": "https://cessda.com/skg-if/api/products/aaa"
              }
          },
          {
              "@id": "https://w3id.org/cessda/product-bbb",
              "as:url": {
                "@type": "as:Link",
                "as:rel": "self",
                "as:href": "https://cessda.com/skg-if/api/products/bbb"
              }
          }
        ]
      
}},
    { "results" : [
    { 
      "@id": "https://w3id.org/cessda/product-bbb",
      "entity_type": "product"
    },
    { 
      "@id": "https://w3id.org/cessda/product-aaa",
      "entity_type": "product"
    },
     { 
      "@id": "https://w3id.org/cessda/product-ccc",
      "entity_type": "product",
  // note it is still possible to have an embedded section producing the same triples as product-bbb and product-aaa with API links in the meta
       "as:url": {
                "@type": "as:Link",
                "as:rel": "self",
                "as:href": "https://example.com/skg-if/api/products/ccc"
       }
     }]}

  ]
}

Playground

[rduyme]

@essepuntato @menzowindhouwer

• Are you ok with the Canonized ?
• Is the json ok. I had to put eveything in the @graph to keep the possibility of having API links inside or outside the meta. and generating the same triple

Note : I will create context aliases for the json "as:*" elements

[essepuntato]

Hi, I haven't time to fully evaluate it now (apologies, I am at a conference), but I'm against to put anything in the @graph if the are alternatives, because those mapping are API-related things and do not concern the content (which is described in the graph) and make it very confusing. Why it is not possible to move it in the "meta" part, that should be external to the @graph as already agreed -- consider that several
implementation of the API have already defined meta externally...

[essepuntato]

Also, why we should specify that entity_type again? Maybe I am missing something, but the @graph part, which is defined via the skg-if data model, cannot be modified.

@rduyme can you explain what are the things that cannot be handled in meta as defined in the api context?

[rduyme]

@essepuntato thanks for the feedback.

why we should specify that entity_type again? => can be removed yes. initial ticket description fixed.

• If we move the meta section out of the graph. The triples generated for product-aaa and product-ccc, for the links, are not the same. (QUADS differ)
  => We can keep meta outside and not include any documentation of product-ccc embedded syntax. And force the user to put all the API links in the meta.

@menzowindhouwer Menzo ok for you ?

BTW : God... there is one guy with at-graph github account... :-)

Final proposition

{
  "@context": [
    "https://w3id.org/skg-if/context/1.1.0/skg-if.json",
    {
      "as": "http://www.w3.org/ns/activitystreams#",
      "meta": "@nest"
    }
    ],
  "meta": {
        "@id": "https://cessda.com/skg-if/api/products?filter=product_type:literature&page=1",
     	"@type": "as:CollectionPage",
      	"as:next": {
            "local_identifier": "https://cessda.com/skg-if/api/products?filter=product_type:literature&page=2",
            "@type": "as:CollectionPage"
          },
      	 "as:partOf": {
            "local_identifier": "https://cessda.com/skg-if/api/products?filter=product_type:literature",
            "@type": "as:Collection",
          	"as:totalItems": 54231
          },
          "as:items" : [
          {
              "@id": "https://w3id.org/cessda/product-aaa",
              "as:url": {
                "@type": "as:Link",
                "as:rel": "self",
                "as:href": "https://cessda.com/skg-if/api/products/aaa"
              }
          },
          {
              "@id": "https://w3id.org/cessda/product-bbb",
              "as:url": {
                "@type": "as:Link",
                "as:rel": "self",
                "as:href": "https://cessda.com/skg-if/api/products/bbb"
              }
          }
        ]
      
},
  "@graph" : [
    { 
      "@id": "https://w3id.org/cessda/product-bbb",
      "entity_type": "product"
    },
    { 
      "@id": "https://w3id.org/cessda/product-aaa",
      "entity_type": "product"
    },
     { 
      "@id": "https://w3id.org/cessda/product-ccc-notallowed-link-syntax",
      "entity_type": "product",
// not allowed link syntax, Kept here to show the triples/quads generated
       "as:url": {
                "@type": "as:Link",
                "as:rel": "self",
                "as:href": "https://cessda.com/skg-if/api/products/ccc-notallowed-link-syntax"
       }
     }
    ]

}

Diff .

<https://w3id.org/cessda/product-aaa> <http://www.w3.org/ns/activitystreams#url> _:c14n2 .
vs
<https://w3id.org/cessda/product-ccc-notallowed-link-syntax> <http://www.w3.org/ns/activitystreams#url> _:c14n1 <https://cessda.com/skg-if/api/products?filter=product_type:literature&page=1> . 

• product-aaa and product-bbb are mapped to their respective URL details (_:c14n2 and _:c14n0) in the Default Graph (as standard Triples).
• product-ccc-notallowed-link-syntax is mapped to its URL details (_:c14n1) inside a Named Graph (as an RDF Quad). The 4th element specifies that this relationship belongs to the API's page=1 graph context. => This will not be allowed

[menzowindhouwer]

We needed the type as the same identifier might appear in different contexts, so needs to be accessed by different API endpoints, e.g. from context via products somewhere else via persons. I would also prefer if that is not needed, but @rduyme you encountered this ambiguity in the real world ... if I understood correctly. But you think its not needed anymore?

[rduyme]

done #64