process | events (Only Internal Use)

1.0.x
(0 reviews)
process deliveries / customer order events (Only Internal Use)

Process | Events API Documentation

Overview and Purpose of the API

The Process | Events API is designed to address the business needs of various events related to Holcim's processes. This API provides endpoints to process delivery events and customer order events, as well as a health check endpoint to monitor the API's status. It ensures seamless integration and communication between different systems by enabling the processing of event-related data in a standardized format.

Authentication Requirements and Security Details

The API includes traits for handling correlation IDs, error responses, and traceparent headers. However, specific authentication mechanisms (e.g., API keys, OAuth) are not explicitly mentioned in the provided input. Ensure that appropriate security measures are implemented when integrating this API.

Base URL and Environments

The API uses the HTTP protocol and supports the application/json media type. The base URL for the API is not explicitly provided in the input. Ensure to configure the correct base URL for the environment (e.g., development, staging, production) where the API is deployed.

Detailed Endpoint Documentation

1. Health Check Endpoint

Method: GET
Path: /health

Description:
This endpoint is used to check the health status of the API. It returns a simple status message indicating whether the API is operational.

Responses:
  • 200 OK: The API is operational.Response Example:
    {
  "status": "UP"
}

2. Process Delivery Event

Method: POST
Path: /documents/deliveries

Description:
This endpoint processes delivery events. It accepts a delivery document in the request body and processes it accordingly.

Traits:
  • Correlation ID: Ensures traceability of requests.
  • Error Handling: Provides structured error responses.
Request Body:
  • Media Type: application/json
  • Schema: delivery.documentDelivery
  • Example:The example for the request body is included in the file examples/POSTDocumentDeliveriesRequest.json. Ensure to refer to this file for the exact structure.
Responses:
  • 204 No Content: The request was successfully processed, and no content is returned.

3. Process Customer Order Event

Method: POST
Path: /documents/customerOrders

Description:
This endpoint processes customer order events. It accepts a customer order document in the request body and processes it accordingly.

Traits:
  • Correlation ID: Ensures traceability of requests.
  • Error Handling: Provides structured error responses.
Request Body:
  • Media Type: application/json
  • Schema: customerOrder.customerOrderDocument
  • Example:The example for the request body is included in the file examples/POSTDocumentCustomerOrder.json. Ensure to refer to this file for the exact structure.
Responses:
  • 204 No Content: The request was successfully processed, and no content is returned.

Error Handling and Status Codes

The API includes structured error handling traits. Below are the common status codes and their meanings:

  • 200 OK: The request was successful, and the response contains the requested data.
  • 204 No Content: The request was successful, but no content is returned.
  • 4xx Client Errors: Errors caused by invalid requests (e.g., malformed syntax, invalid parameters).
  • 5xx Server Errors: Errors caused by issues on the server side.

Ensure to handle errors gracefully and provide meaningful messages to the end user.

Best Practices for Implementation

  • Use Correlation IDs: Include correlation IDs in requests to enable traceability and debugging.
  • Validate Input Data: Ensure that the request body adheres to the required schema before sending it to the API.
  • Monitor API Health: Regularly use the /health endpoint to monitor the API's operational status.
  • Handle Errors Gracefully: Implement robust error handling to manage client and server-side errors effectively.
  • Secure Communication: Use HTTPS for secure communication and implement authentication mechanisms as needed.

Sample Code Snippets

Health Check Example

Request:
curl -X GET http://<base-url>/health
Response:
{
  "status": "UP"
}

Process Delivery Event Example

Request:
curl -X POST http://<base-url>/documents/deliveries \
-H "Content-Type: application/json" \
-d @POSTDocumentDeliveriesRequest.json
Response:
  • 204 No Content

Process Customer Order Event Example

Request:
curl -X POST http://<base-url>/documents/customerOrders \
-H "Content-Type: application/json" \
-d @POSTDocumentCustomerOrder.json
Response:
  • 204 No Content

This documentation provides a comprehensive overview of the Process | Events API, including its endpoints, request/response details, and implementation best practices. Ensure to refer to the provided examples and schemas for accurate integration.

Reviews