feat: adding idempotency to transfers

[pengying]

TL;DR

Added Idempotency-Key header support to transfer endpoints.

What changed?

• Added an optional Idempotency-Key header parameter to the transfer-in and transfer-out API endpoints
• The header allows clients to safely retry requests without risking duplicate transfers
• Included documentation explaining that if the same key is sent multiple times, the server will return the same response as the first request
• Added an example UUID format for the header value: 550e8400-e29b-41d4-a716-446655440000

[pengying]

• feat: adding idempotency to transfers #138 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Greptile Overview

Greptile Summary

Added optional Idempotency-Key header to /transfer-in and /transfer-out endpoints to enable safe request retries without creating duplicate transfers. When the same key is sent multiple times, the server returns the original response.

Key changes:

• Added Idempotency-Key header parameter to both transfer endpoints
• Header is optional and accepts a string value
• Documentation explains retry behavior clearly
• Built OpenAPI files updated correctly

Observations:

• No validation constraints (maxLength, pattern) on the idempotency key
• No 409 Conflict response documented for duplicate requests
• Description could specify key storage duration and behavior with failed requests

Confidence Score: 4/5

• This PR is safe to merge with minimal risk
• Score reflects straightforward documentation-only changes that add optional idempotency support. The changes are syntactically correct and follow OpenAPI standards. Minor deduction for missing validation constraints and response documentation.
• No files require special attention - changes are documentation updates to OpenAPI specs

Important Files Changed

Filename	Overview
openapi/paths/transfers/transfer_in.yaml	Added optional Idempotency-Key header for safe request retries
openapi/paths/transfers/transfer_out.yaml	Added optional Idempotency-Key header for safe request retries
openapi.yaml	Built file correctly includes idempotency key changes
mintlify/openapi.yaml	Built file correctly includes idempotency key changes

Sequence Diagram

sequenceDiagram
    participant Client
    participant API as Grid API
    participant DB as Database
    
    Note over Client,DB: First Request with Idempotency-Key
    Client->>API: POST /transfer-in<br/>Idempotency-Key: abc123
    API->>DB: Check if key exists
    DB-->>API: Key not found
    API->>DB: Store key and initiate transfer
    API-->>Client: 201 Created + Transaction
    
    Note over Client,DB: Retry with Same Idempotency-Key
    Client->>API: POST /transfer-in<br/>Idempotency-Key: abc123
    API->>DB: Check if key exists
    DB-->>API: Key found with stored response
    API-->>Client: 201 Created + Original Transaction<br/>(no duplicate transfer)
    
    Note over Client,DB: New Request with Different Key
    Client->>API: POST /transfer-out<br/>Idempotency-Key: xyz789
    API->>DB: Check if key exists
    DB-->>API: Key not found
    API->>DB: Store key and initiate transfer
    API-->>Client: 201 Created + Transaction

Loading

[greptile-apps]

_{2 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Missing format constraint and maxLength. Consider adding validation to prevent abuse.

Suggested change

	- name: Idempotency-Key
	in: header
	required: false
	description: >
	A unique identifier for the request. If the same key is sent multiple times,
	the server will return the same response as the first request.
	schema:
	type: string
	example: 550e8400-e29b-41d4-a716-446655440000
	parameters:
	- name: Idempotency-Key
	in: header
	required: false
	description: >
	A unique identifier for the request. If the same key is sent multiple times,
	the server will return the same response as the first request.
	schema:
	type: string
	maxLength: 255

Prompt To Fix With AI

This is a comment left during a code review.
Path: openapi/paths/transfers/transfer_in.yaml
Line: 13:21

Comment:
Missing format constraint and maxLength. Consider adding validation to prevent abuse.

```suggestion
  parameters:
    - name: Idempotency-Key
      in: header
      required: false
      description: >
        A unique identifier for the request. If the same key is sent multiple times,
        the server will return the same response as the first request.
      schema:
        type: string
        maxLength: 255
```

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Missing format constraint and maxLength. Consider adding validation to prevent abuse.

Suggested change

	- name: Idempotency-Key
	in: header
	required: false
	description: >
	A unique identifier for the request. If the same key is sent multiple times,
	the server will return the same response as the first request.
	schema:
	type: string
	example: 550e8400-e29b-41d4-a716-446655440000
	parameters:
	- name: Idempotency-Key
	in: header
	required: false
	description: >
	A unique identifier for the request. If the same key is sent multiple times,
	the server will return the same response as the first request.
	schema:
	type: string
	maxLength: 255

Prompt To Fix With AI

This is a comment left during a code review.
Path: openapi/paths/transfers/transfer_out.yaml
Line: 11:19

Comment:
Missing format constraint and maxLength. Consider adding validation to prevent abuse.

```suggestion
  parameters:
    - name: Idempotency-Key
      in: header
      required: false
      description: >
        A unique identifier for the request. If the same key is sent multiple times,
        the server will return the same response as the first request.
      schema:
        type: string
        maxLength: 255
```

How can I resolve this? If you propose a fix, please make it concise.