OpenAPI - Get entity by id . meta local_identifier

[rduyme]

Suggestion Silvio @essepuntato

about the meta issue I've mentioned before, I was wandering why we do not adopt the same approach used for the "search" API query for defining the initial local_identifier in meta, thus specifying the URL of the API query executed instead of the IRI of the requested entity. In practice, in the example in https://skg-if.github.io/api/ now it is:

{
    "meta" : {
        "local_identifier": "https://w3id.org/skg-if/sandbox/acme/prod-1",
        "entity_type": "single_entity",
        "api_items": [ ... ]
    },

while I'm suggesting to use the same approach adopted with the "search" APIs, thus returning:

{
    "meta" : {
        "local_identifier": "https://acme.com/skg-if/api/products/https://w3id.org/skg-if/sandbox/acme/prod-1",
        "entity_type": "single_entity",
        "api_items": [ ... ]
    },

[rduyme]

I agree,

I update to

"local_identifier": "https://acme.com/skg-if/api/products/prod-1", 

API doc is aligned with simple urls

there is an expectation that implementers should resolve both

• "local_identifier": "https://acme.com/skg-if/api/products/https://w3id.org/skg-if/sandbox/acme/prod-1"
• and "local_identifier": "https://acme.com/skg-if/api/products/prod-1",

API like crossref, datacite, openalex are resolving both.

OpenAlex.

• https://api.openalex.org/works/https://openalex.org/W3210097868 => ok
• https://api.openalex.org/works/W3210097868 => ok

Crossref

• http://api.crossref.org/works/https://doi.org/10.1039/d1cb00160d => ok
• http://api.crossref.org/works/10.1039/d1cb00160d => ok

Action :

• update the get by Id
• Add paragraph in https://skg-if.github.io/api/ markdown to explain resolve expectations on get by id

[essepuntato]

Hi @rduyme,

Thanks for sharing this here. I do agree that, from one perspective, the API can help the users to resolve both situations, but from a specification perspective, local_identifier is a URL (i.e. https://w3id.org/skg-if/sandbox/acme/prod-1) and not a simple string (prod-1), and in addition, the way it is handled and shaped is in the hands of the source. Thus, to ensure full compliance across all API implementations, we need to specify the way to request it: via the full URL.

I know that OpenAlex and Crossref implement the facilities you are mentioning (and we do the same in OpenCitations in our APIs), but here we are defining a shared standard that can be used by a wide range of adopters, and thus we need to be consistent, clear, and unambiguous.

Thus, I would suggest, in the documentation, to explicitly say that the sources are expected to implement the API handling with a full URL as local_identifier, i.e.

https://acme.com/skg-if/api/products/https://w3id.org/skg-if/sandbox/acme/prod-1

and that must work to be compliant with the SKG-IF API.

However, in addition to that, each source may implement additional mechanisms that include only the local part of the local_identifier, but that should be documented clearly by the source (and not the official SKG-IF API spec) since only the source knows what the "local" part to consider is. For instance, in Crossref it is 10.1039/d1cb00160d, in OpenAlex it is W3210097868, in OpenCitations it is omid:br/0601, and so on. There is no defined pattern to establish what the local part of a local_identifier is, and as such, it should not be defined explicitly in the SKG-IF API specification.

Summarising: I'm strongly against using the reduced form suggested in the example, https://acme.com/skg-if/api/products/prod-1, since it is not compliant with SKG-IF. Instead, in the documentation of the SKG-IF API specification, please use the full and correct form:

https://acme.com/skg-if/api/products/https://w3id.org/skg-if/sandbox/acme/prod-1

Since this is the only one that the SKG-IF API is obliged to implement, thus making the mechanism shared across all the sources.

@andremann, what do you think?

[essepuntato]

We may, though, specify in the SKG-IF API docs that if a particular way of defining local_identifier in the @graph is used by a source, e.g. in case we use a simple string like prod-1 for specifying a local_identifier of an entity that will be completed by using the base in @base, then the SKG-IF API must also handled that reduced form in the API operations themself.

In practice, if I, as a source, expose data in the following way:

{
    "@context": [
        "https://w3id.org/skg-if/context/1.1.0/skg-if.json",
        "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json",
        { 
            "@base": "https://w3id.org/skg-if/sandbox/acme/"
        }
    ],
    "meta": { ... },
    "@graph": [
        {
            "local_identifier": "prod-1",
            ...
    ]
}

then both the API mechanisms should work, i.e.:

• with full URL (that should always be working): https://acme.com/skg-if/api/products/https://w3id.org/skg-if/sandbox/acme/prod-1
• with short string (which strongly depends on how that is specified by the source): https://acme.com/skg-if/api/products/prod-1

What do you think?

[rduyme]

I will put a MUST and not a SHOULD yes :-).

I am not too worried.
The main use case is a search, and as a client, you are not supposed to build your API URLs client side by randomly getting an API root url and sticking an id. The meta gives you the link, and it is now very flexible.

You can even give API URLs outside of your domain, ex point to DataCite API for a dataset local_identifier : https://doi.org/....

[rduyme]

fixed by .

#67