Understanding Idempotency

When integrating with an API, especially for financial operations, it's important to ensure that actions are not unintentionally duplicated, even if a request is sent multiple times (e.g., due to network issues). Fuze achieves this and ensures data integrity through the use of unique client-defined identifiers for key resources.

ℹ️

Idempotency through Client-Defined IDs

With Fuze, when you create important resources like Users, Transfers, or initiate certain Payments, you often provide a unique identifier. Fuze uses this identifier to recognize and prevent the creation of duplicate records. If you attempt to create a resource with an identifier that already exists, the system will typically acknowledge the existing resource or indicate a conflict, rather than creating a new one.

How Fuze Handles Idempotency via Unique IDs

Fuze's approach to preventing duplication often relies on the unique IDs you assign when creating resources:

1. Client-Provided Unique Identifiers:

   • When you make an API call to create a critical resource (e.g., a new User using a orgUserId you define, or a Transfer with a client-generated transactionId), this ID serves as the primary key for that entity.
   • You are responsible for generating a unique ID from your system for each distinct entity or operation. Using a standard like UUID v4 is recommended for these IDs.

2. Preventing Duplicates at Creation:

   • First Request: When Fuze receives a request to create a resource with a new, unique client-provided ID, the resource is created as expected.
   • Subsequent Requests with the Same ID: If you (or your system due to a retry) send another request to create the same type of resource using the exact same client-provided ID:
     • Fuze's system will recognize that a resource with this ID already exists.
     • It will not create a duplicate resource.
     • The API will typically respond in one of two ways (confirm Fuze's specific behavior):
       • Return the details of the already existing resource (e.g., a 200 OK or 201 Created with the existing resource's data, signaling the "creation" was effectively idempotent as the desired state is met).
       • Return an error indicating a conflict (e.g., 409 Conflict), explicitly stating that a resource with that ID already exists.

3. Querying and Referencing:

   • This client-defined ID then becomes the way you query or refer to that specific resource in subsequent API calls (e.g., fetching user details by their orgUserId, or checking the status of a transfer by its client-provided transferId).

Why This Approach is Beneficial

• Durable Idempotency: This method provides idempotency for the creation operation itself, not just for short-lived network retries. As long as the ID is unique to the intended operation, duplicates are prevented.
• Simplified Client Logic: You manage one primary ID for your resource, which also serves the purpose of preventing duplicates.
• Reliable State Management: You can confidently retry creation requests if you encounter network errors, knowing that if the resource was already created (even if you didn't get the first response), a duplicate won't occur.

Best Practices

• Always use a unique, client-generated ID when the API requires it for creating critical resources (e.g., orgUserId for customers, a unique ID for payment initiation if specified in the API design).
• Store these IDs carefully on your end, associating them with the operation or entity they represent in your system.
• If a creation request fails due to a network error and you're unsure of the outcome: Retry the request with the exact same client-provided ID and request parameters. Observe the API response to understand if it was newly created, if it already existed, or if there was another issue.

👍

Key Takeaway: Your IDs Ensure Uniqueness

By requiring and utilizing unique client-defined identifiers for key resources, Fuze ensures that operations like customer creation or payment initiation are idempotent. Your system's ability to generate and manage these unique IDs is central to preventing accidental duplications.