Single-entity vs list operations disagree on the "nothing found" case

[arcangelo7]

The OpenAPI (https://skg-if.github.io/api/openapi/ver/current/skg-if-openapi.yaml) handles an empty result differently depending on the operation. A lookup by id like /products/{local_identifier} (same for persons, organisations, etc.) defines a 404. On the contrary, list and search operations define a 200 with an empty array in case of zero results.

[rduyme]

Hi @arcangelo7 .

This make sense for me.

• 404 on get by id
• 200 on search

same behaviour on similar APIs

• https://api.openaire.eu/graph/v1/researchProducts/xxx 404
• https://api.openaire.eu/graph/v1/researchProducts?search=xxx 200
• https://api.openalex.org/works/W77777 404
• https://api.openalex.org/works?filter=doi:xxx 200

@menzowindhouwer any strong opinion on this ?

[arcangelo7]

Hi @rduyme, thanks for looking into this.

I see your point and the examples are fair, OpenAIRE and OpenAlex do that. But I think there is a difference here. In those APIs the get by id response and the search response have different shapes: a single resource is an object, while the search/filter result is an array.

Here the situation is different. As far as I can tell from the spec, every response is a collection, even when you ask for a single entity.

I am not saying either choice is wrong, both are reasonable. My point is that, since the output container is the same in both cases, it would be nice to settle on one behaviour rather than two for what is essentially the same outcome, no result found.

[menzowindhouwer]

I like the 404 in the singular lookup and an empty result in the case of a search. But I also see the point from @arcangelo7, that we use the same envelop for both so we could align them ... we should take it to the upcoming meeting ...

[essepuntato]

Something to discuss for sure, indeed. I add just another aspect to the discussion. Technically speaking, we always return a list of entities in all the operations (i.e. via the keyword @graph that is always a list of objects...).

[rduyme]

Discussed today in RDA WG.

• get by id 404 - if not found
• search 404 - on empty search as well. because of semantic RDF vision :-)

[essepuntato]

Let me add more detail to justify what we discussed in the last SKG-IF meeting, held on 12 June 2026, regarding the use of the 200 and 404 status codes when replying via the API. Before that, a few premises are necessary to substantiate the approach.

Preliminaries

1. Always a collection of entities

Independent of the type of API operation we execute (either get an entity by local identifier or search for entities compliant with specific filters), the API always returns a collection of entities within the @graph field - which forms the actual response of the API query – accompanied by metadata of the API request contained in the field meta. For instance, this is an appropriate answer to an API request like /products/https://w3id.org/oc/meta/br/06103843235:

{
    "@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"
    ],
    "meta": { ... },
    "@graph": [
        {
            "local_identifier": "https://w3id.org/oc/meta/br/06103843235",
            "entity_type": "product",
            ...
            "contributions": [
                {
                    "role": "author",
                    "by": https://w3id.org/oc/meta/ra/061012076859,
                    "rank": 1
                },
                ...
            ],
            ...
        },
        {
            "local_identifier": "https://w3id.org/oc/meta/ra/061012076859",
            "name": "Leithäuser, N.",
            "entity_type": "person",
            "family_name": "Leithäuser",
            "given_name": "N."
        }
    ]
}

As you can see, while the API request refers to a specific entity (https://w3id.org/oc/meta/br/06103843235), that entity refers to other entities, such as a person who is an author of the requested entity. This person may be defined as injected into the field by, specifying a JSON object directly there, or (as in the example) referred to by its local identifier and then properly defined in the result set returned within an appropriate JSON object. Thus, as clarified here, I can require one entity from the API, but the answer could be a list of entities that include the one requested plus those related to it.

2. It is RDF

What is returned by the API, from a formal point of view, is a set of RDF statements - that, for convenience, we are exposing using JSON-LD to enable also Web developers, who may not be experts in Semantic Web technologies, to parse them as regular JSON. Please note that the entire response must be treated as a set of RDF statements, some of which are defined within the meta field (representing metadata for the API request) and others are defined in the @graph field (representing the actual content being the answer to the original API request).

3. What RFC 9110 says about HTTP 404

The RFC 9119 defines the semantics of HTTP. Among the various descriptive elements it contains, it also provides some definitions about the status codes that should be returned within an HTTP communication process, and one of those is the famous 404 that is defined as follows (bold is mine):

The 404 (Not Found) status code indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists. A 404 status code does not indicate whether this lack of representation is temporary or permanent; the 410 (Gone) status code is preferred over 404 if the origin server knows, presumably through some configurable means, that the condition is likely to be permanent.

Now, since in the Web exists the open world assumption, which is indeed particularly relevant when Semantic Web technologies enter into play, any request made (via using a specific URI) to a server may not be satisfied in the sense that it may not have, currently, information about the requested in the format (i.e. the representation) required. It does not mean the resource does not exist; it means the server has no information about it.

It is important to frame that, even in the presence of a 404, the server should return something. In fact, as the RFC 9110 says, at the beginning of the section on 4xx status codes (bold is mine):

Except when responding to a HEAD request, the server SHOULD send a representation containing an explanation of the error situation, and whether it is a temporary or permanent condition. These status codes are applicable to any request method. User agents SHOULD display any included representation to the user.

This is exactly what happens when we access a resource (e.g. an HTML page) via a browser. If the server does not have any information about that resource, it returns a 404, but it also provides, in the payload of the HTTP response, an HTML detailing what happened.

The SKG-IF API implementation of status codes

Now, let us consider such premises as starting points - i.e. the fact that we always return a collection of entities, that we are returning RDF (part of it concerning the metadata of the API request, and another part dedicated to the actual content of the request), and the HTTP 404 definition that opens up to different interpretation without failing the HTTP semantics. According to those, we have two possibilities for SKG-IF API responses (independently of the actual operation called):

• (A) We return an HTTP 200 OK if the SKG-IF API endpoints find some answers (i.e. it has a representation in JSON-LD format of the requested resource, which is injected in the @graph field) and we return an HTTP 404 Not Found otherwise (where the @graph field is an empty array);

• (B) We always return HTTP 200 OK for any response possible response, without caring about the actual content of the @graph field.

Both these solutions are reasonable and compliant with HTTP Semantics.

Reasons in favour of (A)

The rationale for supporting the first solution (A) among the above possibilities during the last SKG-IF meeting was pragmatic (as all the choices we have made so far in the group). The final goal is to help adopters (i.e. developers) process the information returned by the APIs as easily as possible.

In the case of adopting solution (A), I can immediately determine whether the API returns what I requested simply by looking at the HTTP status code. Indeed, if an HTTP 404 Not Found is returned, I already know the response contains nothing for me, so I can move on without wasting time opening and processing the response payload (unless I am interested in gathering more information about the metadata of the API request). Thus, I have to process the response only if the answer is positive (i.e. HTTP 200 OK).

Reasons against (B)

If we use solution (B) instead, I need to open the payload anyway and parse it to determine whether an actual answer to my original request is contained there. And here I can have two possible scenarios (with different results!) depending on the point of view I am adopting here:

• Perspective of a pure Web developer - I look at the field @graph and if the array there contains something, I infer that there is an answer for my original API request. If @graph refers to an empty array, I can infer that there is no answer for my original request. This choice moves the correct interpretation of the answer to a syntactical analysis of the JSON-LD response received, bypassing completely the actual semantic level provided by HTTP Semantics (which does not help with meaningful status codes) and the RDF semantics, which do not discriminate between the two cases at all (there is an answer vs. there is no answer to the original request).

• Perspective of a Semantic Web expert - I see the answer as a set of RDF statements, which is always full of some information (considering that the meta field will be populated at least). However, since the RDF statements are there, I have no way to determine whether that set contains the answer to my original request. In this case, I do not have enough information to understand the status of the answer received.

Conclusions

The final goal we have, as the SKG-IF WG, is to provide adopters with a solution that is clear, unambiguous, uniform across the SKG-IF specifications, and that helps our users. To me, but this is a personal view, choosing (B) goes against these principles, and (A) seems to be a simple, standard-compliant solution that solves already plenty of problems without touching the JSON-LD payload of the response we defined.

Then the SKG-IF WG may choose to use (B). Of course, as mentioned above, it is a solution that is "reasonable and compliant with HTTP Semantics," as I said. But if that choice is made, I would love to see pragmatic justifications for going in that direction, with the goal of simplifying adopters' lives. Very honestly, but this is my personal perspective, I admit, saying that we support a solution because others have done it before (even if in different contexts) does not sound like a robust argument in favour of a solution, since they may have considered different kinds of users and different starting premises which differ from ours.

My 2 cents.

S.