Add Revision and Latest Revision in the JSON object response

[aloccid-iata]

Problem Statement

Currently, the version of an object is provided only in the response header of a GET API call. When a user retrieves an object using the query parameter embedded=true, a collection of objects is returned, but only the revision of the main object is included. As a result, the user must make an additional GET API call to obtain the version of any nested objects.

Proposed Solution

To eliminate the need for a second API call, we propose including the version information directly in the JSON-LD response using the api ontology properties :

• https://onerecord.iata.org/ns/api#hasRevision
• https://onerecord.iata.org/ns/api#hasLatestRevision

Example provided by @ddoeppner:

HTTP/1.1 200 OK
Content-Type: application/ld+json
Content-Language: en-US
Location: https://1r.example.com/logistics-objects/1a8ded38-1804-467c-a369-81a411416b3c
Type: https://onerecord.iata.org/ns/cargo#Shipment
Revision: 1
Latest-Revision: 1
Last-Modified: Tue, 21 Feb 2023 07:28:00 GMT

{
    "@context": {
        "cargo": "https://onerecord.iata.org/ns/cargo#",
        "api": "https://onerecord.iata.org/ns/api#"
    },
    "@type": "cargo:Shipment",
    "api:hasLatestRevision": 1,
    "api:hasRevision": 1,
    "cargo:goodsDescription": "Lots of awesome ONE Record information materials",    
    "cargo:pieces": [
        {
            "@type": "cargo:Piece",
            "@id": " https://1r.example.com/logistics-objects/1a8ded38-1804-467c-a369-81a411416b7c",
            "cargo:coload": {
                "@type": "http://www.w3.org/2001/XMLSchema#boolean",
                "@value": "false"
            },
            "api:hasLatestRevision": 3,
            "api:hasRevision": 3,
            "cargo:specialHandlingCodes": [
                {
                    "@id": "https://onerecord.iata.org/ns/coreCodeLists#SpecialHandlingCode_VAL"
                }
            ]
        }
    ]
}

[ddoeppner]

Sounds reasonable. I vote in favour of 'Create a new property in the API ontology', as such information is meta information and would be better placed in the more technical API ontology rather than the business-oriented Cargo ontology.

In the current API specification, we already have the HTTP header fields: see https://iata-cargo.github.io/ONE-Record/stable/API-Security/logistics-objects/#response_1

Header	Description	Example
Revision	The revision of the requested logistics object as a positive numerical value. This is particularly relevant if the query parameter at= is set to request a historical version of the logistics object.	3
Latest-Revision	The last revision number of the logistics object as a non-negative numerical value.	3

How about using the same naming for the properties?

Example: from https://iata-cargo.github.io/ONE-Record/stable/API-Security/logistics-objects/#example-b1

HTTP/1.1 200 OK
Content-Type: application/ld+json
Content-Language: en-US
Location: https://1r.example.com/logistics-objects/1a8ded38-1804-467c-a369-81a411416b7c
Type: https://onerecord.iata.org/ns/cargo#Piece
Revision: 1
Latest-Revision: 1
Last-Modified: Tue, 21 Feb 2023 07:28:00 GMT

{
    "@context": {
        "cargo": "https://onerecord.iata.org/ns/cargo#",
        "api": "https://onerecord.iata.org/ns/api#",
        "@language": "en-US"
    },
    "@type": "cargo:Piece",
    "@id": " https://1r.example.com/logistics-objects/1a8ded38-1804-467c-a369-81a411416b7c",
    "api:hasLatestRevision": 1,
    "api:hasRevision": 1,
    "cargo:coload": false,
    "cargo:specialHandlingCodes": [
        {
            "@id": "https://onerecord.iata.org/ns/coreCodeLists#SpecialHandlingCode_VAL"
        }
    ]
}

Best regards, Daniel

[ddoeppner]

Additional example with ?embedded=true

With Shipment (rev=1) and linked Piece (rev=3)

HTTP/1.1 200 OK
Content-Type: application/ld+json
Content-Language: en-US
Location: https://1r.example.com/logistics-objects/1a8ded38-1804-467c-a369-81a411416b3c
Type: https://onerecord.iata.org/ns/cargo#Shipment
Revision: 1
Latest-Revision: 1
Last-Modified: Tue, 21 Feb 2023 07:28:00 GMT

{
    "@context": {
        "cargo": "https://onerecord.iata.org/ns/cargo#",
        "api": "https://onerecord.iata.org/ns/api#"
    },
    "@type": "cargo:Shipment",
    "api:hasLatestRevision": 1,
    "api:hasRevision": 1,
    "cargo:goodsDescription": "Lots of awesome ONE Record information materials",    
    "cargo:pieces": [
        {
            "@type": "cargo:Piece",
            "@id": " https://1r.example.com/logistics-objects/1a8ded38-1804-467c-a369-81a411416b7c",
            "cargo:coload": {
                "@type": "http://www.w3.org/2001/XMLSchema#boolean",
                "@value": "false"
            },
            "api:hasLatestRevision": 3,
            "api:hasRevision": 3,
            "cargo:specialHandlingCodes": [
                {
                    "@id": "https://onerecord.iata.org/ns/coreCodeLists#SpecialHandlingCode_VAL"
                }
            ]
        }
    ]
}

[NiclasScheiber]

The issue and the proposed solutions are reasonable. I support handling the issue as suggested by @ddoeppner, using the existing vocabulary of the api ontology

• https://onerecord.iata.org/ns/api#hasRevision
• https://onerecord.iata.org/ns/api#hasLatestRevision

I would not create new properties api#revision and api#latestRevision if they are the same as the pre-existing ones.

[ddoeppner]

The issue and the proposed solutions are reasonable. I support handling the issue as suggested by @ddoeppner, using the existing vocabulary of the api ontology

• https://onerecord.iata.org/ns/api#hasRevision

• https://onerecord.iata.org/ns/api#hasLatestRevision

I would not create new properties api#revision and api#latestRevision if they are the same as the pre-existing ones.

Right! I overlooked the existence of these two... makes absolutely sense to reuse them!

Edit: I updated the examples above accordingly.

[aloccid-iata]

HI @ddoeppner and @NiclasScheiber,

I definitely support your idea! I will update the issue with your suggestions.

Best, Davide

[aloccid-iata]

Issue description updated

[app87]

Thanks Davide, Nivclas, Daniel for this~!

This API enhancement proposal if approved, would be extremely useful in optimizing API calls, especially when LOs are being updated. This is because any change request/ patch request to update an LO needs to have the specific version against which the request is being triggered ---- which is possible only if the LO is fetched via GET LO. If there are multiple LOs in a use case that has changed, the above proposed solution would help eliminate patch requestors from triggering individual GET LO calls for the sole purpose of retrieving the version number.

[aloccid-iata]

Approved by API working group on the 16/09/2024

[aloccid-iata]

This issue has been added into the documentation and will be sent for approval to the COTB