Action Requests

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:

• An ActionRequest MUST be accessible via the URI of the ActionRequest (requires sufficient permissions)
• An ActionRequest MUST only be accepted or reject by the Holder of the LogisticsObject
• A VerificationRequest MUST only be acknowledged by the Holder of the LogisticsObject
• An ActionRequest where isRequestedBy is the Holder of the LogisticsObject SHOULD be accepted and processed directly.
• An ActionRequest MUST only be revoked as long as it is in REQUEST_PENDING status.
• An AccessDelegationRequest MUST only be revoked by the Delegator or the Delegate
• A SubscriptionRequest MUST only be revoked by the Requestor/Subscriber or the Publisher
• A VerificationRequest MUST only be revoked by the Requestor or the Holder of the LogisticsObject
• If errors occur while processing an accepted ActionRequest, the hasRequestStatus of this ActionRequest MUST be changed to REQUEST_FAILED

ActionRequest state diagram for AccessDelegationRequest, ChangeRequest, and SubscriptionRequest

    stateDiagram-v2

    direction LR   

    [*] --> REQUEST_PENDING

    REQUEST_PENDING --> REQUEST_ACCEPTED: accepted by holder
    REQUEST_PENDING --> REQUEST_REJECTED: rejected by holder
    REQUEST_PENDING --> REQUEST_REVOKED: revocation requested

    REQUEST_REVOKED --> [*]

    REQUEST_ACCEPTED --> [*]        
    REQUEST_ACCEPTED --> REQUEST_FAILED:  an error has occurred        

    REQUEST_FAILED --> [*]

    REQUEST_REJECTED --> [*]    

ActionRequest state diagram for VerificationRequest

    stateDiagram-v2

    direction LR   

    [*] --> REQUEST_PENDING

    REQUEST_PENDING --> REQUEST_ACKNOWLEDGED: acknowledged by holder
    REQUEST_PENDING --> REQUEST_REJECTED: rejected by holder
    REQUEST_PENDING --> REQUEST_REVOKED: revocation requested
    REQUEST_PENDING --> REQUEST_FAILED: revocation requested

    REQUEST_REVOKED --> [*]      

    REQUEST_FAILED --> [*]

    REQUEST_REJECTED --> [*]    

    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

    direction LR   

    class LogisticsObject{                
    }

    class Organization{        
    }  

    class AccessDelegation{
        + hasDescription: xsd:string [0..1]
        + hasPermission[]: Permission [1..*]                
        + isRequestedFor[]: Organization [1..*]
        + notifyRequestStatusChange: xsd:boolean = FALSE
        + hasLogisticsObject[]: LogisticsObject [1..*]        
    }

    AccessDelegation "1" --> "1..*" Permission   
    AccessDelegation "1" --> "1..*" Organization: requestedFor
    AccessDelegation "1" --> "1..*" LogisticsObject

    class ActionRequest {
        <<Abstract>>         
        + hasError[]: Error [*]
        + isRequestedAt: xsd:dateTime         
        + isRequestedBy: Organization            
        + isRevokedBy: Organization [0..1]
        + hasRequestStatus: RequestStatus = REQUEST_PENDING
        + isRevokedAt: xsd:dateTime [0..1]                 
    }
    ActionRequest <|-- AccessDelegationRequest
    ActionRequest <|-- ChangeRequest
    ActionRequest <|-- SubscriptionRequest

    ActionRequest "1" --> "0..*" Error     
    ActionRequest "1" --> "1..*" Organization : requestedBy    
    ActionRequest --> RequestStatus                
    ActionRequest "1" --> "1..*" Organization : revokedBy

    class AccessDelegationRequest{
        + hasAccessDelegation: AccessDelegation        
    }
    AccessDelegationRequest "1" --> "1" AccessDelegation    

    class ChangeRequest{        
        + hasChange: Change        
    }    
    ChangeRequest "1" --> "1" Change

    class SubscriptionRequest{
        + hasSubscription: Subscription
    }   
    SubscriptionRequest "1" --> "1" Subscription

    class VerificationRequest{
        + hasVerification: Verification
    }   
    VerificationRequest"1" --> "1" Verification

    class Change{    
        + hasDescription: xsd:string [0..1]    
        + hasOperation[]: Operation [1..*]        
        + hasLogisticsObject: LogisticsObject
        + hasRevision: xsd:positiveInteger        
        + notifyRequestStatusChange: xsd:boolean = FALSE
    }
    Change "1" --> "1" LogisticsObject
    Change "1" --> "1..*" Operation

    class Subscription{        
        + hasContentType[]: xsd:string [*]
        + hasDescription: xsd:string [0..1]
        + expiresAt: xsd:dateTime [0..1]                                
        + hasSubscriber: Organization        
        + hasTopicType: TopicType
        + notifyRequestStatusChange: xsd:boolean = FALSE          
        + sendLogisticsObjectBody: xsd:boolean = FALSE        
        + includeSubscriptionEventType[]: SubscriptionEventType [1..*]
        + hasTopic: xsd:anyURI        
    }    
    Subscription "1" --> "1" Organization: hasSubscriber
    Subscription --> TopicType
    Subscription "1" --> "1..*" SubscriptionEventType

    class Verification{      
        + hasLogisticsObject: LogisticsObject
        + hasError[]: Error[1..*]        
        + hasRevision: xsd:positiveInteger        
        + notifyRequestStatusChange: xsd:boolean = FALSE
    }
    Verification "1" --> "1" LogisticsObject
    Verification "1" --> "1..*" Error

    class RequestStatus{
        <<Enumeration>>
        REQUEST_PENDING
        REQUEST_ACCEPTED
        REQUEST_ACKNOWLEDGED
        REQUEST_REJECTED
        REQUEST_FAILED
        REQUEST_REVOKED        
    }

    class SubscriptionEventType{
        <<Enumeration>>
        LOGISTICS_OBJECT_CREATED
        LOGISTICS_OBJECT_UPDATED

        LOGISTICS_EVENT_RECEIVED
    }

Get Action Request Details

Endpoint

 GET {{baseURL}}/action-requests/{{actionRequestId}}

Request

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.	application/ld+json application/ld+json; version=2.0.0-dev application/ld+json; version=1.2

Response

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

Security

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.

Example A1

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
Host: 1r.example.com
Accept: application/ld+json; version=2.0.0-dev

Response:

HTTP/1.1 200 OK
Content-Type: application/ld+json; version=2.0.0-dev
Content-Language: en-US
Location: https://1r.example.com/action-requests/599fea49-7287-42af-b441-1fa618d2aaed
Type: https://onerecord.iata.org/ns/api#SubscriptionRequest
Last-Modified: Tue, 21 Feb 2023 07:28:00 GMT

{
    "@context": {
        "api": "https://onerecord.iata.org/ns/api#"
    },
    "@type": "api:SubscriptionRequest",
    "@id": "https://1r.example.com/action-requests/599fea49-7287-42af-b441-1fa618d2aaed",
    "api:hasSubscription": {
        "@type": "api:Subscription",
        "@id": "internal:84891422-0215-519b-b551-bfb41d0519cd",
        "api:hasContentType": "application/ld+json",
        "api:hasSubscriber": {
            "@id": "https://1r.example.com/logistics-objects/957e2622-9d31-493b-8b8f-3c805064dbda"
        },
        "api:hasTopicType": {
            "@id": "api:LOGISTICS_OBJECT_IDENTIFIER"
        },
        "api:includeSubscriptionEventType": [
            {
                "@id": "api:LOGISTICS_OBJECT_UPDATED"
            },
            {
                "@id": "api:LOGISTICS_OBJECT_CREATED"
            },
            {
                "@id": "api:LOGISTICS_EVENT_RECEIVED"
            }
        ],
        "api:hasTopic": {
            "@type": "http://www.w3.org/2001/XMLSchema#anyURI",
            "@value": "https://1r.example.com/logistics-objects/1a8ded38-1804-467c-a369-81a411416b7c"
        }
    },
    "api:isRequestedBy": {
        "@id": "https://1r.example.com/logistics-objects/957e2622-9d31-493b-8b8f-3c805064dbda"
    },
    "api:hasRequestStatus": {
        "@id": "api:REQUEST_PENDING"
    },
    "api:isRequestedAt": {
        "@type": "http://www.w3.org/2001/XMLSchema#dateTime",
        "@value": "2023-04-20T10:38:01.000Z"
    }
}

(SubscriptionRequest_example2.json)

Example A2

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
Host: 1r.example.com
Accept: application/ld+json; version=2.0.0-dev

Response:

HTTP/1.1 200 OK
Content-Type: application/ld+json; version=2.0.0-dev
Content-Language: en-US
Location: https://1r.example.com/action-requests/e4cf1ea5-96fc-4025-be21-159b779e3200
Type: https://onerecord.iata.org/ns/api#VerificationRequest
Last-Modified: Tue, 02 Jul 2024 10:45:00 GMT

{
    "@context":{
       "api":"https://onerecord.iata.org/ns/api#"
    },
    "@type":"api:VerificationRequest",
    "@id":"https://1r.example.com/action-requests/e4cf1ea5-96fc-4025-be21-159b779e3200",
    "api:hasVerification":{
       "@type":"api:Verification",
       "api:hasLogisticsObject":{
          "@id":"https://1r.example.com/logistics-objects/1a8ded38-1804-467c-a369-81a411416b7c"
       },
       "api:hasError":[
          {
             "@type":"api:Error",
             "api:hasTitle":"Empty goodsDescription. Please use goodsDescription to specify the description of the cargo",
             "api:hasErrorDetail":{
                "@type":"api:ErrorDetail",
                "api:hasProperty":{
                   "@value":"https: //onerecord.iata.org/ns/cargo#goodsDescription",
                   "@type":"xsd:anyURI"
                }
             }
          }
       ],
       "api:hasRevision":{
          "@type":"http: //www.w3.org/2001/XMLSchema#positiveInteger",
          "@value":"1"
       },
       "api:notifyRequestStatusChange":true
    },
    "api:isRequestedBy":{
       "@id":"https://1r.example.com/logistics-objects/957e2622-9d31-493b-8b8f-3c805064dbda"
    },
    "api:hasRequestStatus":{
       "@id":"api:REQUEST_PENDING"
    },
    "api:isRequestedAt":{
       "@type":"http://www.w3.org/2001/XMLSchema#dateTime",
       "@value":"2024-01-20T10:38:01.000Z"
    }
 }

(VerificationRequest.json)

Update an Action Request

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.

Endpoint

 PATCH {{baseURL}}/action-requests/{{actionRequestId}}

Request

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.	https://onerecord.iata.org/ns/api#REQUEST_ACCEPTED or REQUEST_ACCEPTED https://onerecord.iata.org/ns/api#REQUEST_REJECTED or REQUEST_REJECTED https://onerecord.iata.org/ns/api#REQUEST_REVOKED or REQUEST_REVOKED

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.	application/ld+json application/ld+json; version=2.0.0-dev application/ld+json; version=1.2
Content-Type	The content type that is contained with the HTTP body.	application/ld+json application/ld+json; version=2.0.0-dev application/ld+json; version=1.2

Response

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

Security

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

Example B1

Request:

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

Response:

HTTP/1.1 204 No Content
Content-Type: application/ld+json; version=2.0.0-dev
Type: https://onerecord.iata.org/ns/api#SubscriptionRequest
Location: https://1r.example.com/action-requests/733ed391-ad11-4c02-a2bf-c77ee7997c28

Revoke Action Request

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.

Endpoint

 DELETE {{baseURL}}/action-requests/{{actionRequestId}}

Request

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

Response

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

Security

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.

Example C1

Request:

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

Response:

HTTP/1.1 204 No Content