Add Support for HTTP HEAD Method for Logistics Objects

[ddoeppner]

Add Support for HTTP HEAD Method for Logistics Objects

Description

We propose adding an HTTP HEAD method endpoint to check the existence and metadata of a logistics object without requiring retrieval of the full object. This will enable users to efficiently check if the latest version of a resource has changed or obtain key metadata (like Last-Modified, Type, Revision, Latest-Revision, etc.) to validate their cache, thereby improving user experience and reducing unnecessary network traffic.

The HEAD method aligns with standard HTTP practices and is particularly useful for large resources or for applications relying on real-time updates.

Additionally, it might make sense to extend support for the HEAD method to other endpoints, such as Action-Requests (to check if the status has changed) and LogisticsEvents (to verify updates or existence), for a more consistent and efficient API experience.

---

Proposed Feature

1. Endpoint: Add support for the HEAD method on existing logistics objects endpoints.
2. Behavior:
   • Returns the same HTTP headers as a GET request but without the response body.
   • Handles authorization and permission checks similar to the GET request.

---

Benefits

• Efficiency: Allows clients to validate cached objects or check updates without transferring full payloads.
• Standards Compliance: Aligns with HTTP standards for supporting the HEAD method.
• Improved User Experience: Reduces network overhead and improves response time for ONE Record clients.

---

Example Scenarios

LO Exists (200 OK)

Request:

HEAD /logistics-objects/1a8ded38-1804-467c-a369-81a411416b7c HTTP/1.1
Host: 1r.example.com
Accept: application/ld+json; version=2.0.0-dev
Authorization: Bearer <token>

Response:

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
Content-Length: 526

LO Not Found (404 Not Found)

Request*:

HEAD /logistics-objects/1a8ded38-1804-467c-a369-81a411416b7d HTTP/1.1
Host: 1r.example.com
Accept: application/ld+json; version=2.0.0-dev
Authorization: Bearer <token>

Response:

HTTP/1.1 404 Not Found
Content-Type: application/ld+json

No Access to LO (401 or 403)

401 and 403 are similar to 404

Implementation Notes

1. Consistency with GET: The HEAD request should return the same HTTP headers as a GET request but without the response body.
2. Authentication & Authorization: HEAD requests must trigger the same authentication and permission checks as GET.
   Supported Metadata:
3. Error Handling: Properly handle and return appropriate HTTP status codes (e.g., 404 for not found, 401 for unauthorized, and 403 for forbidden).

Further considerations:

• Extend to Other Endpoints: Consider adding HEAD support for /action-requests and /logistics-events endpoints to check for action request has been updated or the existence of LogisticsEvents more efficiently.

--

Feel free to provide feedback or suggest adjustments to this proposal!