Idempotency in Order Creation

In this section, we will discuss the importance of idempotency in our API, particularly focusing on the 'create order' endpoint.

What is Idempotency?

Idempotency is a crucial property of API endpoints, ensuring that repeated identical requests have the same effect as a single request. This is especially important when dealing with orders and transactions to prevent duplicates and maintain data consistency.

Implementing Idempotency in the 'Create Order' Endpoint

To maintain idempotency in our 'create order' endpoint, we utilize the external_id field in the request payload. This required string accepts up to 255 characters and lets Giftogram recognize duplicate requests. In v1, order external IDs are scoped to the account associated with the API key. Persist an ID for each intended order and reuse it when retrying.

When an order is created with a specific external_id, any subsequent requests with the same external_id will be recognized by the system. If the initial request was processed successfully, the subsequent requests simply return the successful order, preventing the creation of duplicate orders.

A newly created order returns 201; a successful replay returns the existing order with 200. Reusing an external ID does not update the recipient, amount, or message of that order. Use a new ID only when you intend to create a separate order.

Benefits of Idempotency

Implementing idempotency in your API offers several benefits:

1. Data Consistency: By preventing duplicate orders, idempotency ensures that your system maintains accurate and consistent data.
2. Simplified Error Recovery: If a request fails due to network issues or other transient errors, you can safely retry the request without worrying about creating duplicate orders.
3. Reliable Deliverability: Idempotency prevents duplicate order creation when you retry. Delivery can still depend on processing and funding; check order and recipient statuses separately.

Best Practices

To effectively implement idempotency in your API, consider the following best practices:

• Use a unique, client-generated identifier for the external_id field.
• Ensure that the external_id is included in all relevant requests and responses.
• Design your system to handle idempotency at the application level, rather than relying solely on the database or other infrastructure components.