From 6f8019ac7b102f009589b2d3b6af63d46afe70a5 Mon Sep 17 00:00:00 2001 From: IATA-Cargo Date: Fri, 23 Aug 2024 13:19:53 +0000 Subject: [PATCH] Deployed da0dc68 to development with MkDocs 1.6.0 and mike 2.1.3 --- development/Orchestration/placi/index.html | 175 ++++++++++++++++++--- development/search/search_index.json | 2 +- 2 files changed, 150 insertions(+), 27 deletions(-) diff --git a/development/Orchestration/placi/index.html b/development/Orchestration/placi/index.html index b61682f2..55444525 100644 --- a/development/Orchestration/placi/index.html +++ b/development/Orchestration/placi/index.html @@ -2073,9 +2073,64 @@
  • - + - Use case #1: Freight forwarder filing pre-loading data for Consolidation shipment + Process #1: Freight forwarder filing pre-loading data for Consolidation shipment + + + +
    • + +
  • + + + Process #2: Freight forwarder filing pre-loading data for non-consolidation shipment + + + +
    • + +
  • + + + Process #3: Associate Master with already filed HAWB + + + + +
    • + + + + @@ -2919,9 +2979,64 @@
  • - + + + Process #1: Freight forwarder filing pre-loading data for Consolidation shipment + + + +
    • + +
  • + + + Process #2: Freight forwarder filing pre-loading data for non-consolidation shipment + + + +
    • + +
  • + + + Process #3: Associate Master with already filed HAWB + + + + +
    • + + + + @@ -2985,31 +3105,34 @@

    General comments applying to

    It is considered that required information for PLACI purposes is already defined in ONE Record realm as House and Master Waybill data should already be recorded and shared between upstream stakeholders (Shipper, Freight Forwarder, Airline, GHA at least)

    -

    Use case #1: Freight forwarder filing pre-loading data for Consolidation shipment

    +

    Process #1: Freight forwarder filing pre-loading data for Consolidation shipment

    Specificity of this process is that: - Freight forwarder has an agreement with Airline to file data on its behalf. - Data is filed at House level for consolidated shipment.

    -

    mermaid -graph TD - A[Freight Forwarder notifies that HAWB content is ready - Event on Shipment] --> B[Customs validates content]; - B --> C{Validation succesful?}; - C -->|Yes| D[Customs notifies that Shipment is OK - Event on Shipment SR]; - C -->|No| E[Customs notifies that there is an error - Event on Shipment Error]; - D --> F{Additional information or screening needed?}; - F -->|Yes| G[Customs notifies RFI or RFS - Event on Shipment RFI or RFS]; - F -->|No| H{Risk assessment completed?}; - H -->|Yes| I{Assessment outcome}; - I -->|Blocked - RFI or RFS| J[CB - 7H, 7J, 8H, 8J]; - I -->|Customs Hold - DNL| K[CD - 6H, 6J]; - I -->|Customs Release - OK| L[CO - SF, 6I, 7I, 8I]; - D --> M[Freight Forwarder notified automatically]; - E --> M; - G --> M; - J --> M; - K --> M; - L --> M; - M --> N{MAWB# available?}; - N -->|Yes| O[Carrier notified automatically via the MAWB object];

    +

    image

    +

    In this scenario, the Freight Forwarder notifies the Customs that data is ready to be processed via an Event on the Shipment object. Then based on Customs validation and risk assessment, different Events are added on the Shipment by the Customs via the Change Request mechanism.

    +

    If there is a MAWB number available, usually the Waybill objects of the House and the Master are already linked and the Airline can get notified automatically if Events are created.

    +

    Process #2: Freight forwarder filing pre-loading data for non-consolidation shipment

    +

    Specificity of this process is that: +- Freight forwarder has an agreement with Airline to file data on its behalf. +- Data is filed at Master level.

    +

    image

    +

    In this scenario the mechanism is very similar, main difference is that information is shared on Master level. Notifications happen with the same mechanisms.

    +

    Process #3: Associate Master with already filed HAWB

    +

    This process represents the scenario when House Waybill have been filed and the Freight Forwarder or the Airline provides sufficient information to Customs to make the link betweem House(s) and the Master.

    +

    With messaging standards, 2 scenarios are outlined based on XFZB update (addition of MAWB number) or XFHL (List of House(s) linked to one Master).

    +

    With ONE Record, those messages are not necessary and updating the HAWB and/or MAWB objects should be sufficient. An Event on the Shipment or Waybill objects can also be used for more clarity.

    +

    We can have 4 different methods, or starting points for the process, depending on the stakeholder notifying the association of Master and House(s) or depending on the fact that the House or the Master is the starting point.

    +

    image

    +

    Below processes #3.1 and #3.3 can be equivalent to sending an update of XFZB while processes #3.2 and #3.4 are equivalent to generating and sending an XFHL message.

    + +

    The Freight Forwarder updates HAWB objects by adding a link to the MAWB object. Customs get notified of the change OR and Event can be added on the HAWB to notify the association has been made.

    + +

    Difference with #3.1 is that the Airline initiates the change. A Change Request mechanism is started as the Freight Forwarder is the owner of the HAWB object. Once the HAWB objects are notified, process is the same to go through Customs.

    + +

    The Freight Forwarder updates the MAWB object with links to all HAWB objects. Customs get notified of the change OR and Event can be added on the MAWB to notify the association has been made.

    + +

    Difference with #3.1 is that the Airline initiates the change. A Change Request mechanism is started as the Freight Forwarder is the owner of the HAWB object. Once the HAWB objects are notified, process is the same to go through Customs.

    diff --git a/development/search/search_index.json b/development/search/search_index.json index 231e266c..66d09da6 100644 --- a/development/search/search_index.json +++ b/development/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Introduction","text":"

    Welcome to ONE Record Standard Specifications!

    "},{"location":"#what-is-one-record","title":"What is ONE Record?","text":"

    The vision for ONE Record is an end-to-end digital logistics and transport supply chain where data is easily and transparently exchanged in a digital ecosystem of air cargo stakeholders, communities and data platforms.

    ONE Record is a standard for data sharing and creates a single record view of the shipment. This standard defines a common data model for the data that is shared via standardized and secured web API.

    You can find further information about ONE Record standard on the IATA dedicated webpage and on the ONE Record Developer Portal.

    "},{"location":"#structure-of-the-documentation","title":"Structure of the documentation","text":""},{"location":"API-Security/","title":"Introduction","text":""},{"location":"API-Security/#purpose","title":"Purpose","text":"

    This ONE Record API specification is part of the ONE Record standard. It defines a standard, programming language-agnostic interface for the interaction with the ONE Record Web API. This ONE Record API specification supports the effective implementation of ONE Record compliant APIs. It aims to provide detailed realistic use cases and examples for the various API features while maintaining the necessary technical depth for implementers.

    "},{"location":"API-Security/#prerequisites","title":"Prerequisites","text":"

    It is assumed that the reader is familiar with the ONE Record data model, REST APIs (also known as RESTful APIs), and JSON-LD.

    "},{"location":"API-Security/#supporting-documents","title":"Supporting Documents","text":""},{"location":"API-Security/#document-version","title":"Document Version","text":"

    Version: 2.0.0

    Status: Endorsed by COTB on December 2023

    Note

    Discussion on this specification is highly encouraged and please contact onerecord@iata.org with any comments or suggested improvements. The version of the ONE Record API specification is incremented when the API specifications are endorsed by the IATA Cargo Operations Technology Board (COTB).

    "},{"location":"API-Security/#dependencies","title":"Dependencies","text":"

    The ontology of the ONE Record API uses data classes defined in the ONE Record cargo ontology. Therefore, this ONE Record API version 2.0.0 requires the ONE Record cargo ontology 3.0.0 or later.

    "},{"location":"API-Security/#conventions","title":"Conventions","text":"

    The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"NOT RECOMMENDED\", \"MAY\", and \"OPTIONAL\" in this document are to be interpreted as described in RFC 2119.

    "},{"location":"API-Security/#license","title":"License","text":"

    This document is licensed under MIT license (see License for details).

    "},{"location":"API-Security/access-delegations/","title":"Access Delegations","text":"

    In ONE Record, parties can grant other parties access to their data (or parts of it). The ONE Record standard allows parties to change or revoke these access rights to their data whenever they wish.

    Before an organization can access a LogisticsObject of another organization, it needs to be authorized to do so and the server that hosts the logistics objects will determine whether to grant access. Typically, when an participant creates a LogisticsObject and makes it available via its ONE Record API, the IoL participant will share the URI of that LogisticsObject with another IoL participant and grant them access by default.

    For example, a freight forwarder creates a Shipment, grants read access to an airline, and then sends the URI of the Logistics Object via a ONE Record Notification or other channel to the airline.

    It might happen that the Airline needs access to additional Logistics objects linked to the Shipment (i.e.: Piece). In this case, the Airline MAY request the access delegation directly from the freight forwarder (Example A1)

    At this point, only the forwarder and the airline can access this specific LogisticsObjects, but no one else.

    However, if a ground handling agent (GHA) also needs access to this logistics object, the airline MAY request an access delegation for the GHA (Example A2).

    If, as in this presented scenario, the airline already has a delegation of access to the logistics object, the concept of Trust Chains takes effect.

    Note

    The party granting access is referred to as the Delegator and the party receiving access is the Delegate. The party requesting access is referred to as the Requestor.

    Guidelines for Access Delegations in ONE Record:

    "},{"location":"API-Security/access-delegations/#request-access-delegation","title":"Request Access Delegation","text":""},{"location":"API-Security/access-delegations/#endpoint","title":"Endpoint","text":"
     POST {{baseURL}}/access-delegations\n
    "},{"location":"API-Security/access-delegations/#request","title":"Request","text":"

    The following HTTP header parameters MUST be present in the request:

    Header Description Examples Accept The content type that the ONE Record client wants the HTTP response to be formatted in. application/ld+json Content-Type The content type that is contained with the HTTP body. Valid content types. application/ld+json

    The HTTP request body must contain a valid AccessDelegation object in the format as specified by the Content-Type in the header.

    The AccessDelegation is a data class of the ONE Record API ontology. The properties and relationships to other data classes are visualized in the diagram.

    classDiagram\n    direction LR\n\n    class LogisticsObject{                \n    }\n\n    class Organization{        \n    }  \n    class AccessDelegation{\n        + hasDescription: xsd:string [0..1]\n        + hasPermission[]: Permission [1..*]                \n        + isRequestedFor[]: Organization [1..*]\n        + notifyRequestStatusChange: xsd:boolean = FALSE\n        + hasLogisticsObject[]: LogisticsObject [1..*]        \n    }\n\n    AccessDelegation \"1\" --> \"1..*\" Permission   \n    AccessDelegation \"1\" --> \"1..*\" Organization: requestedFor\n    AccessDelegation \"1\" --> \"1..*\" LogisticsObject\n\n    class Permission{\n        <<Enumeration>>\n        GET_LOGISTICS_EVENT\n        GET_LOGISTICS_OBJECT\n        PATCH_LOGISTICS_OBJECT\n        POST_LOGISTICS_EVENT\n    }
    "},{"location":"API-Security/access-delegations/#response","title":"Response","text":"

    A successful request MUST return a HTTP/1.1 201 Created status code and the following HTTP headers parameters MUST be present in the response:

    Header Description Examples Location The URI of the newly created AccessDelegationRequest https://1r.example.com/action-requests/b6c24b63-405c-5cc3-ac88-9b109bb939ba Type The type of the newly created AccessDelegationRequest as a URI https://onerecord.iata.org/ns/api#AccessDelegationRequest

    The following HTTP status codes MUST be supported:

    Code Description Response body 201 Request for delegation was successful No response body 400 Invalid Access Delegation object Error 401 Not authenticated Error 403 Not authorized to submit Delegation Request Error 415 Unsupported Content Type Error 500 Internal Server Error Error"},{"location":"API-Security/access-delegations/#security","title":"Security","text":"

    To engage with the \"Request Access Delegation\" endpoint, a client needs proper authentication. If requests lack proper authentication, the ONE Record server should respond with a 401 \"Not Authenticated\" status.

    "},{"location":"API-Security/access-delegations/#example-a1","title":"Example A1","text":"

    An organization requests an access delegation for itself for the Piece with the URI https://1r.example.com/logistics-objects/1a8ded38-1804-467c-a369-81a411416b7c

    Request: 

    POST /access-delegations HTTP/1.1\nContent-Type: application/ld+json; version=2.0.0-dev\nAccept: application/ld+json; version=2.0.0-dev\n\n{\n    \"@context\": {\n        \"cargo\": \"https://onerecord.iata.org/ns/cargo#\",\n        \"api\": \"https://onerecord.iata.org/ns/api#\"\n    },\n    \"@type\": \"api:AccessDelegation\",\n    \"api:hasDescription\": \"Require access to Piece for handling\",\n    \"api:hasPermission\": [{\n            \"@id\": \"api:GET_LOGISTICS_OBJECT\"\n        }\n    ],\n    \"api:isRequestedFor\": [{\n        \"@id\": \"https://1r.example.com/logistics-objects/Airline_XYZ\"\n    }],\n    \"api:notifyRequestStatusChange\": false,\n    \"api:hasLogisticsObject\": [{\n        \"@id\": \"https://1r.example.com/logistics-objects/1a8ded38-1804-467c-a369-81a411416b7c\"\n    }]\n}\n
    (AccessDelegation_example1.json)

    Response: 

    HTTP/1.1 201 Created\nLocation: https://1r.example.com/action-requests/b6c24b63-405c-5cc3-ac88-9b109bb939ba\nContent-Type: application/ld+json; version=2.0.0-dev\nType: https://onerecord.iata.org/ns/api#AccessDelegationRequest\n

    Note

    The Requestor linked the isRequestedBy property in the created AccessDelegationRequest and the Delegate linked in the isRequestedFor property in the AccessDelegation are the same.

    "},{"location":"API-Security/access-delegations/#example-a2","title":"Example A2","text":"

    An organization requests an access delegation for a business partner for the Piece with the URI https://1r.example.com/logistics-objects/1a8ded38-1804-467c-a369-81a411416b7c

    Request: 

    POST /access-delegations HTTP/1.1\nContent-Type: application/ld+json; version=2.0.0-dev\nAccept: application/ld+json; version=2.0.0-dev\n\n{\n    \"@context\": {\n        \"cargo\": \"https://onerecord.iata.org/ns/cargo#\",\n        \"api\": \"https://onerecord.iata.org/ns/api#\"\n    },\n    \"@type\": \"api:AccessDelegation\",\n    \"api:hasDescription\": \"Our GHA requires read access to Piece for handling\",\n    \"api:hasPermission\": [{\n            \"@id\": \"api:GET_LOGISTICS_OBJECT\"\n        }\n    ],\n    \"api:isRequestedFor\": [{\n        \"@id\": \"https://1r.example.com/logistics-objects/GHA_ABC\"\n    }],\n    \"api:notifyRequestStatusChange\": false,\n    \"api:hasLogisticsObject\": [{\n        \"@id\": \"https://1r.example.com/logistics-objects/1a8ded38-1804-467c-a369-81a411416b7c\"\n    }]\n}\n
    (AccessDelegation_example2.json)

    Response: 

    HTTP/1.1 201 Created\nLocation: https://1r.example.com/action-requests/1d2d3807-5dd9-5b5b-acb6-26163a6d7411\nContent-Type: application/ld+json; version=2.0.0-dev\nType: https://onerecord.iata.org/ns/api#AccessDelegationRequest\n

    Note

    The Requestor associated with the isRequestedBy property in the created AccessDelegationRequest is different from the Delegate linked in the isRequestedFor property in the AccessDelegation. The Requestor must be derived from the API authentication mechanism identifying who is making the request.

    "},{"location":"API-Security/access-delegations/#trust-chains","title":"Trust Chains","text":"

    Trust chains are based on business partnerships and trust in the transport chain. It ensures that the company who has shared a logistics object, always knows who MAY access the data and at any time, it can revoke all or part of the chain of trust.

    Therefore, the concept described in the previous sections can be used by organizations to delegate access to their partners, which become 3rd parties. In the example above, the airline can request that the forwarder gives access to their ground handler. The forwarder will grant the access on the basis that they trust the airline who trusts their ground handler.

    However, if the holder of the logistics object withdraws access delegation to a second party, it MUST be ensured that the third party's access delegation is also withdrawn.

    See also the section about revoking Action Requests.

    "},{"location":"API-Security/action-requests/","title":"Action Requests","text":"

    ONE Record uses a generic action request pattern to support the process of one organization requesting an action that must be approved by another organization. Examples include SubscriptionRequest, where the subscriber asks the publisher to subscribe him/her on a LogisticsObject; or the ChangeRequest, where a User of a LogisticsObject submits a Change of a LogisticsObject that must be approved and applied by the Holder of the LogisticsObject.

    While the creation of Action Requests by submitting Change, Subscription or Access Delegation objects is described in the previous sections, this section describes the managing of Action Requests. This enables users and holders to view and revoke action requests, and enables holders to change the status of an ActionRequest, i.e. to accept or reject.

    Guidelines for Action Requests in ONE Record:

    ActionRequest state diagram for AccessDelegationRequest, ChangeRequest, and SubscriptionRequest

        stateDiagram-v2\n\n    direction LR   \n\n    [*] --> REQUEST_PENDING\n\n    REQUEST_PENDING --> REQUEST_ACCEPTED: accepted by holder\n    REQUEST_PENDING --> REQUEST_REJECTED: rejected by holder\n    REQUEST_PENDING --> REQUEST_REVOKED: revocation requested\n\n    REQUEST_REVOKED --> [*]\n\n    REQUEST_ACCEPTED --> [*]        \n    REQUEST_ACCEPTED --> REQUEST_FAILED:  an error has occurred        \n\n    REQUEST_FAILED --> [*]\n\n    REQUEST_REJECTED --> [*]

    ActionRequest state diagram for VerificationRequest

        stateDiagram-v2\n\n    direction LR   \n\n    [*] --> REQUEST_PENDING\n\n    REQUEST_PENDING --> REQUEST_ACKNOWLEDGED: acknowledged by holder\n    REQUEST_PENDING --> REQUEST_REJECTED: rejected by holder\n    REQUEST_PENDING --> REQUEST_REVOKED: revocation requested\n    REQUEST_PENDING --> REQUEST_FAILED: revocation requested\n\n    REQUEST_REVOKED --> [*]      \n\n    REQUEST_FAILED --> [*]\n\n    REQUEST_REJECTED --> [*]    \n\n    REQUEST_ACKNOWLEDGED --> [*]

    ActionRequest data model

    The ActionRequest is a data class of the ONE Record API ontology. The properties and relationships to other data classes are visualized in the following class diagram.

        classDiagram\n\n    direction LR   \n\n    class LogisticsObject{                \n    }\n\n    class Organization{        \n    }  \n\n    class AccessDelegation{\n        + hasDescription: xsd:string [0..1]\n        + hasPermission[]: Permission [1..*]                \n        + isRequestedFor[]: Organization [1..*]\n        + notifyRequestStatusChange: xsd:boolean = FALSE\n        + hasLogisticsObject[]: LogisticsObject [1..*]        \n    }\n\n    AccessDelegation \"1\" --> \"1..*\" Permission   \n    AccessDelegation \"1\" --> \"1..*\" Organization: requestedFor\n    AccessDelegation \"1\" --> \"1..*\" LogisticsObject\n\n    class ActionRequest {\n        <<Abstract>>         \n        + hasError[]: Error [*]\n        + isRequestedAt: xsd:dateTime         \n        + isRequestedBy: Organization            \n        + isRevokedBy: Organization [0..1]\n        + hasRequestStatus: RequestStatus = REQUEST_PENDING\n        + isRevokedAt: xsd:dateTime [0..1]                 \n    }\n    ActionRequest <|-- AccessDelegationRequest\n    ActionRequest <|-- ChangeRequest\n    ActionRequest <|-- SubscriptionRequest\n\n    ActionRequest \"1\" --> \"0..*\" Error     \n    ActionRequest \"1\" --> \"1..*\" Organization : requestedBy    \n    ActionRequest --> RequestStatus                \n    ActionRequest \"1\" --> \"1..*\" Organization : revokedBy\n\n    class AccessDelegationRequest{\n        + hasAccessDelegation: AccessDelegation        \n    }\n    AccessDelegationRequest \"1\" --> \"1\" AccessDelegation    \n\n    class ChangeRequest{        \n        + hasChange: Change        \n    }    \n    ChangeRequest \"1\" --> \"1\" Change\n\n    class SubscriptionRequest{\n        + hasSubscription: Subscription\n    }   \n    SubscriptionRequest \"1\" --> \"1\" Subscription\n\n    class VerificationRequest{\n        + hasVerification: Verification\n    }   \n    VerificationRequest\"1\" --> \"1\" Verification\n\n    class Change{    \n        + hasDescription: xsd:string [0..1]    \n        + hasOperation[]: Operation [1..*]        \n        + hasLogisticsObject: LogisticsObject\n        + hasRevision: xsd:positiveInteger        \n        + notifyRequestStatusChange: xsd:boolean = FALSE\n    }\n    Change \"1\" --> \"1\" LogisticsObject\n    Change \"1\" --> \"1..*\" Operation\n\n    class Subscription{        \n        + hasContentType[]: xsd:string [*]\n        + hasDescription: xsd:string [0..1]\n        + expiresAt: xsd:dateTime [0..1]                                \n        + hasSubscriber: Organization        \n        + hasTopicType: TopicType\n        + notifyRequestStatusChange: xsd:boolean = FALSE          \n        + sendLogisticsObjectBody: xsd:boolean = FALSE        \n        + includeSubscriptionEventType[]: SubscriptionEventType [1..*]\n        + hasTopic: xsd:anyURI        \n    }    \n    Subscription \"1\" --> \"1\" Organization: hasSubscriber\n    Subscription --> TopicType\n    Subscription \"1\" --> \"1..*\" SubscriptionEventType\n\n    class Verification{      \n        + hasLogisticsObject: LogisticsObject\n        + hasError[]: Error[1..*]        \n        + hasRevision: xsd:positiveInteger        \n        + notifyRequestStatusChange: xsd:boolean = FALSE\n    }\n    Verification \"1\" --> \"1\" LogisticsObject\n    Verification \"1\" --> \"1..*\" Error\n\n    class RequestStatus{\n        <<Enumeration>>\n        REQUEST_PENDING\n        REQUEST_ACCEPTED\n        REQUEST_ACKNOWLEDGED\n        REQUEST_REJECTED\n        REQUEST_FAILED\n        REQUEST_REVOKED        \n    }\n\n    class SubscriptionEventType{\n        <<Enumeration>>\n        LOGISTICS_OBJECT_CREATED\n        LOGISTICS_OBJECT_UPDATED\n\n        LOGISTICS_EVENT_RECEIVED\n    }
    "},{"location":"API-Security/action-requests/#get-action-request-details","title":"Get Action Request Details","text":""},{"location":"API-Security/action-requests/#endpoint","title":"Endpoint","text":"
     GET {{baseURL}}/action-requests/{{actionRequestId}}\n
    "},{"location":"API-Security/action-requests/#request","title":"Request","text":"

    The following HTTP header parameters MUST be present in the request:

    Header Description Examples Accept The content type that a ONE Record client wants the HTTP response to be formatted in. This SHOULD include the version of the ONE Record API, otherwise the latest supported ONE Record API MAY be applied. "},{"location":"API-Security/action-requests/#response","title":"Response","text":"

    A successful request MUST return a HTTP/1.1 200 OK status code. The body of the response includes the Action Request in the RDF serialization format that has been requested in the Accept header of the request.

    The following HTTP headers parameters MUST be present in the response:

    Header Description Example Content-Type The content type that is contained with the HTTP body. application/ld+json Content-Language Describes the language(s) for which the requested resource is intended. en-US Type The type of the Action Request as a URI https://onerecord.iata.org/ns/api#SubscriptionRequest Last-Modified he date and time of the most recent change to the Action Request. Syntax: Last-Modified: <day-name>, <day> <month> <year> <hour>:<minute>:<second> GMT. See https://developer.mozilla.org/en-US/docs/Web/ Tue, 21 Feb 2023 07:28:00 GMT

    The following HTTP status codes MUST be supported:

    Code Description Response body 200 The request to retrieve the Action Request has been successful Action Request 301 The URI of the Action Request has permanently changed. No response body 302 The URI of the Action Request has temporarily moved. No response body 401 Not authenticated Error 403 Not authorized to retrieve the Action Request Error 404 Action Request not found Error 415 Unsupported Content Type Error 500 Internal Server Error Error"},{"location":"API-Security/action-requests/#security","title":"Security","text":"

    To engage with the \"Get Action Request Details\" endpoint, a client needs proper authentication and authorization to access the designated resource. If requests lack proper authentication, the ONE Record server should respond with a 401 \"Not Authenticated\" status. Conversely, for requests without proper authorization, a 403 \"Not Authorized\" response should be provided.

    "},{"location":"API-Security/action-requests/#example-a1","title":"Example A1","text":"

    Each SubscriptionRequest MUST have a URI that can be accessed by the requestor (subscriber) and the publisher to obtain the current status of the request and subscription details.

    Request:

    GET /action-requests/599fea49-7287-42af-b441-1fa618d2aaed HTTP/1.1\nHost: 1r.example.com\nAccept: application/ld+json; version=2.0.0-dev\n

    Response:

    HTTP/1.1 200 OK\nContent-Type: application/ld+json; version=2.0.0-dev\nContent-Language: en-US\nLocation: https://1r.example.com/action-requests/599fea49-7287-42af-b441-1fa618d2aaed\nType: https://onerecord.iata.org/ns/api#SubscriptionRequest\nLast-Modified: Tue, 21 Feb 2023 07:28:00 GMT\n\n{\n    \"@context\": {\n        \"api\": \"https://onerecord.iata.org/ns/api#\"\n    },\n    \"@type\": \"api:SubscriptionRequest\",\n    \"@id\": \"https://1r.example.com/action-requests/599fea49-7287-42af-b441-1fa618d2aaed\",\n    \"api:hasSubscription\": {\n        \"@type\": \"api:Subscription\",\n        \"@id\": \"internal:84891422-0215-519b-b551-bfb41d0519cd\",\n        \"api:hasContentType\": \"application/ld+json\",\n        \"api:hasSubscriber\": {\n            \"@id\": \"https://1r.example.com/logistics-objects/957e2622-9d31-493b-8b8f-3c805064dbda\"\n        },\n        \"api:hasTopicType\": {\n            \"@id\": \"api:LOGISTICS_OBJECT_IDENTIFIER\"\n        },\n        \"api:includeSubscriptionEventType\": [\n            {\n                \"@id\": \"api:LOGISTICS_OBJECT_UPDATED\"\n            },\n            {\n                \"@id\": \"api:LOGISTICS_OBJECT_CREATED\"\n            },\n            {\n                \"@id\": \"api:LOGISTICS_EVENT_RECEIVED\"\n            }\n        ],\n        \"api:hasTopic\": {\n            \"@type\": \"http://www.w3.org/2001/XMLSchema#anyURI\",\n            \"@value\": \"https://1r.example.com/logistics-objects/1a8ded38-1804-467c-a369-81a411416b7c\"\n        }\n    },\n    \"api:isRequestedBy\": {\n        \"@id\": \"https://1r.example.com/logistics-objects/957e2622-9d31-493b-8b8f-3c805064dbda\"\n    },\n    \"api:hasRequestStatus\": {\n        \"@id\": \"api:REQUEST_PENDING\"\n    },\n    \"api:isRequestedAt\": {\n        \"@type\": \"http://www.w3.org/2001/XMLSchema#dateTime\",\n        \"@value\": \"2023-04-20T10:38:01.000Z\"\n    }\n}\n
    (SubscriptionRequest_example2.json)

    "},{"location":"API-Security/action-requests/#example-a2","title":"Example A2","text":"

    After requesting a Verification of a LogisticsObject (see Example A1 in Verifications), the requestor can retrieve the VerificationRequest to check the status.

    Request: 

    GET /action-requests/e4cf1ea5-96fc-4025-be21-159b779e3200 HTTP/1.1\nHost: 1r.example.com\nAccept: application/ld+json; version=2.0.0-dev\n

    Response:

    HTTP/1.1 200 OK\nContent-Type: application/ld+json; version=2.0.0-dev\nContent-Language: en-US\nLocation: https://1r.example.com/action-requests/e4cf1ea5-96fc-4025-be21-159b779e3200\nType: https://onerecord.iata.org/ns/api#VerificationRequest\nLast-Modified: Tue, 02 Jul 2024 10:45:00 GMT\n\n{\n    \"@context\":{\n       \"api\":\"https://onerecord.iata.org/ns/api#\"\n    },\n    \"@type\":\"api:VerificationRequest\",\n    \"@id\":\"https://1r.example.com/action-requests/e4cf1ea5-96fc-4025-be21-159b779e3200\",\n    \"api:hasVerification\":{\n       \"@type\":\"api:Verification\",\n       \"api:hasLogisticsObject\":{\n          \"@id\":\"https://1r.example.com/logistics-objects/1a8ded38-1804-467c-a369-81a411416b7c\"\n       },\n       \"api:hasError\":[\n          {\n             \"@type\":\"api:Error\",\n             \"api:hasTitle\":\"Empty goodsDescription. Please use goodsDescription to specify the description of the cargo\",\n             \"api:hasErrorDetail\":{\n                \"@type\":\"api:ErrorDetail\",\n                \"api:hasProperty\":{\n                   \"@value\":\"https: //onerecord.iata.org/ns/cargo#goodsDescription\",\n                   \"@type\":\"xsd:anyURI\"\n                }\n             }\n          }\n       ],\n       \"api:hasRevision\":{\n          \"@type\":\"http: //www.w3.org/2001/XMLSchema#positiveInteger\",\n          \"@value\":\"1\"\n       },\n       \"api:notifyRequestStatusChange\":true\n    },\n    \"api:isRequestedBy\":{\n       \"@id\":\"https://1r.example.com/logistics-objects/957e2622-9d31-493b-8b8f-3c805064dbda\"\n    },\n    \"api:hasRequestStatus\":{\n       \"@id\":\"api:REQUEST_PENDING\"\n    },\n    \"api:isRequestedAt\":{\n       \"@type\":\"http://www.w3.org/2001/XMLSchema#dateTime\",\n       \"@value\":\"2024-01-20T10:38:01.000Z\"\n    }\n }\n
    (VerificationRequest.json)

    "},{"location":"API-Security/action-requests/#update-an-action-request","title":"Update an Action Request","text":"

    This API action can be used the holder/publisher of a Logistics Object to approve or reject a pending ActionRequest.

    For example, as a publisher, this API action is used to change the status of a received Subscription Request on a ONE Record server using the PATCH HTTP method.

    Note

    Although the updating the state of of a Subscription Request is specified in the ONE Record API specification, it is not required to expose an API endpoint for this API action to be compliant with the ONE Record standard. The reason for this is that only the holder of the logistics object MAY accept or reject a subscription request with any business logic or technology.

    Nevertheless, this API action specification is included for reference, because in many cases, the use of HTTP PATCH is the preferred solution to update resources with REST APIs.

    "},{"location":"API-Security/action-requests/#endpoint_1","title":"Endpoint","text":"
     PATCH {{baseURL}}/action-requests/{{actionRequestId}}\n
    "},{"location":"API-Security/action-requests/#request_1","title":"Request","text":"

    The following query parameters MUST be supported:

    Query parameter Description Valid values status A parameter used to configure the status of an Action request. This operation modifies the status of the Action Request based on the value specified in the status parameter.

    The following HTTP header parameters MUST be present in the request:

    Header Description Examples Accept The content type that a ONE Record client wants the HTTP response to be formatted in. This SHOULD include the version of the ONE Record API, otherwise the latest supported ONE Record API MAY be applied. Content-Type The content type that is contained with the HTTP body. "},{"location":"API-Security/action-requests/#response_1","title":"Response","text":"

    A successful request MUST return a HTTP/1.1 204 No Content status code and the following HTTP headers parameters MUST be present in the response:

    Header Description Example Location The URI of the Action Request https://1r.example.com/action-requests/6b948f9b-b812-46ed-be39-4501453da99b Type The type of the Action Request as a URI https://onerecord.iata.org/ns/api#ChangeRequest

    Otherwise, an Error object with ErrorDetail as response body MUST be returned with the following HTTP headers:

    Header Description Example Content-Type The content type that is contained with the HTTP body. application/ld+json Content-Language Describes the language(s) for which the requested resource is intended. en-US

    The following HTTP status codes MUST be supported:

    Code Description Response body 204 The Action Request was successfully updated No body required 400 The update request body is invalid Error 401 Not authenticated Error 403 Not authorized to update the Action Request Error 404 Action Request not found Error 415 Unsupported Content Type, response when the client sends a PATCH document format that the server does not support for the resource identified by the Request-URI. Error 422 Unprocessable request, when the server understands the PATCH document and the syntax of the PATCH document appears to be valid, but the server is incapable of processing the request. Error 500 Internal Server Error Error"},{"location":"API-Security/action-requests/#security_1","title":"Security","text":"

    Access to the Action Request update endpoint should be restricted to internal usage only, and it must not be made available to external entities.

    "},{"location":"API-Security/action-requests/#example-b1","title":"Example B1","text":"

    Request:

    PATCH /action-requests/733ed391-ad11-4c02-a2bf-c77ee7997c28?status=https://onerecord.iata.org/ns/api#REQUEST_ACCEPTED HTTP/1.1\nHost: 1r.example.com\nContent-Type: application/ld+json; version=2.0.0-dev\nAccept: application/ld+json; version=2.0.0-dev\n

    Response:

    HTTP/1.1 204 No Content\nContent-Type: application/ld+json; version=2.0.0-dev\nType: https://onerecord.iata.org/ns/api#SubscriptionRequest\nLocation: https://1r.example.com/action-requests/733ed391-ad11-4c02-a2bf-c77ee7997c28\n
    "},{"location":"API-Security/action-requests/#revoke-action-request","title":"Revoke Action Request","text":"

    This API action MUST be used to revoke an Action Request MUST be revoked only by the original requestor of the ActionRequest or the holder/publisher of the Logistics Object.

    "},{"location":"API-Security/action-requests/#endpoint_2","title":"Endpoint","text":"
     DELETE {{baseURL}}/action-requests/{{actionRequestId}}\n
    "},{"location":"API-Security/action-requests/#request_2","title":"Request","text":"

    Revoking an Action Rquest does not require any mandatory HTTP headers.

    "},{"location":"API-Security/action-requests/#response_2","title":"Response","text":"

    A successful request MUST return a HTTP/1.1 204 No Content status code.

    The following HTTP status codes MUST be supported:

    Code Description Response body 204 The Action Request was successfully deleted No body required 401 Not authenticated Error 403 Not authorized to update the Action Request Error 404 Action Request not found Error 500 Internal Server Error Error"},{"location":"API-Security/action-requests/#security_2","title":"Security","text":"

    To engage with the \"Revoke Action Request\" endpoint, a client needs proper authentication and authorization to access the designated resource. If requests lack proper authentication, the ONE Record server should respond with a 401 \"Not Authenticated\" status. Conversely, for requests without proper authorization, a 403 \"Not Authorized\" response should be provided.

    "},{"location":"API-Security/action-requests/#example-c1","title":"Example C1","text":"

    Request: 

    DELETE /action-requests/449661ee-fecf-465d-8eae-15bdaccb7080 HTTP/1.1\nHost: 1r.example.com\n

    Response: 

    HTTP/1.1 204 No Content\n

    "},{"location":"API-Security/api-features/","title":"Overview","text":""},{"location":"API-Security/api-features/#api-features","title":"API Features","text":"

    The following features summarize all of the ONE Record API features

    Get ONE Record Server Information Anyone who has access to a ONE Record server can retrieve the technical server meta information that contains information about supported features, supported ONE Record API version, supported ONE Record data model version, etc.

    Create and publish a Logistics Object - Anyone who controls a ONE Record server can create a new Logistics Object based on the ONE Record data model specification. Once created the Logistics Object is associated with a unique URI that makes the Logistics Object available on the network.

    Read a Logistics Object - Logistics Objects can be retrieved by calling the URI of that Logistics Object - its Logistics Object URI. Access rights to that Logistics Object URI is managed by the Holder of the Logistics Object.

    Update a Logistics Object - As a fundamental principle, only the Holder of a Logistics Object can make changes to it. Therefore, changes required by other parties are expressed as Change Requests that needs to be approved and executed by the actual holder.

    Subscribe to a Logistics Object for updates - Once a Logistics Object has been created, the holder can propose subscriptions to other parties who will then be notified of any changes. Other parties may also request such a subscription at the discretion of the holder.

    Create Logistics Event linked with Logistics Objects - Logistics Events like \"arrival\", \"acceptance\" etc. are central in the management of logistics and transport. Every participant in the network with sufficient access rights can submit any type of Logistics Event to any published Logistics Object.

    Read Logistics Event linked to a Logistics Object - Every participant of the network with sufficient permissions, can also query the Logistics Events associated with a Logistics Object.

    Manage access to a Logistics Object - Another fundamental principle of ONE Record is that only holders of Logistics Objects have fully control access rights to that Logistics Object. Therefore, only the holder of a Logistics Object can delegate permissions to users of the Logistics Object.

    Delegate access to a Logistics Object to a third party - By default, most Logistics Objects are not public accessible. Most of the time, access is granted to specific parties. Should these parties need to delegate access to further stakeholders - because they require data access to fulfil their logistics activities- then there is a mechanism for requesting such access to the holder of the Logistics Object.

    Manage and access versions of Logistics Objects - Each time a logistics object is updated by a change in data, this change is recorded in an audit trail. This automatically creates a new version of the Logistics Object. Each version of the logistics object SHOULD be found and retrieved.

    API security - Although not strictly an API feature, ONE Record specifies security measures for implementation on web servers such that access to the server may be identified, authenticated and authorized.

    "},{"location":"API-Security/api-features/#api-endpoints","title":"API Endpoints","text":"HTTP Methods API Endpoint API Function GET / Retrieve ServerInformation POST /logistics-objects/ Create Logistics Object. This endpoint could be either internal or not implemented. GET, PATCH /logistics-objects/{logisticsObjectId} Retrieve Logistics Object and links to related resources GET /logistics-objects/{logisticsObjectId}/audit-trail Retrieve Audit Trail of a Logistics Object GET, POST /logistics-objects/{logisticsObjectId}/logistics-events Create or retrieve LogisticsEvents to a Logistics Object GET /logistics-objects/{logisticsObjectId}/logistics-events/{LogisticsEvent URI} Retrieve a LogisticsEvent GET, POST /subscriptions Create or retrieve Subscription information for a Logistics Object type or a specific LogisticsObjectIdentifier GET, PATCH, DELETE /action-requests Create, retrieve, or update Action Request (i.e. SubscriptionRequests, ChangeRequests or AccessDelegationRequests) POST /notifications Receive Notifications POST /access-delegations Create, retrieve, or update Access Delegation Request"},{"location":"API-Security/bibliography/","title":"Bibliography","text":""},{"location":"API-Security/changelog/","title":"Changelog","text":"

    All notable changes to this project will be documented in this file.

    The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

    "},{"location":"API-Security/changelog/#210-dev","title":"2.1.0-dev","text":""},{"location":"API-Security/changelog/#ideas","title":"Ideas","text":""},{"location":"API-Security/changelog/#one-record-api-specification","title":"ONE Record API Specification","text":""},{"location":"API-Security/changelog/#changed","title":"Changed","text":""},{"location":"API-Security/changelog/#200","title":"2.0.0","text":""},{"location":"API-Security/changelog/#one-record-api-specification_1","title":"ONE Record API Specification","text":""},{"location":"API-Security/changelog/#changed_1","title":"Changed","text":""},{"location":"API-Security/changelog/#removed","title":"Removed","text":""},{"location":"API-Security/changelog/#added","title":"Added","text":""},{"location":"API-Security/changelog/#one-record-api-ontology","title":"ONE Record API Ontology","text":""},{"location":"API-Security/changelog/#changed_2","title":"Changed","text":"