Integration Best Practices - old

This guide outlines best practices for developers integrating with the Reveel PayID API. Following these principles will help ensure a reliable, secure, and scalable integration.

---

1. Authentication Best Practices

• Always include the following headers in every request:

  Authorization: Bearer your-api-key
  Accept: application/json
  Content-Type: application/json  // For POST/PUT/DELETE

• Store API keys securely — never expose them in frontend code or public repositories.

• If your backend supports it, rotate API keys periodically and use environment variables for injection.

---

2. Use Idempotent Requests

• Avoid duplicate actions by ensuring critical POST operations (e.g., route creation, transaction initialization) are idempotent on your side using:

  • Idempotency keys (UUID v4 stored per action)

  • Client-side tracking of previously submitted data

• While the Reveel API does not currently enforce idempotency keys natively, it’s a good client-side practice to avoid accidental duplicates (e.g., resubmitting forms or retrying after a timeout).

---

3. Graceful Error Handling

• All errors follow a consistent format:

  {
    "success": false,
    "message": "Descriptive error",
    "error": "Field-level validation or server error details"
  }

• Parse the response safely and display human-readable messages to users, especially for known issues like:

  • PayID already taken

  • Route conflict detected

  • Invalid token/network combination

• Fallback to generic messages (e.g., "Something went wrong") only when necessary.

---

4. Retry Logic & Backoff

• Implement retry with exponential backoff for transient errors like 500 or timeouts.

• Do not retry on:

  • 400 Bad Request

  • 401 Unauthorized

  • 409 Conflict

• Consider adding retry safeguards:

  • Max 3 retries

  • Backoff (e.g. 1s, 2s, 4s)

---

5. Pagination & Rate Control

• For endpoints like /user/list and /transact/get-activity, always:

  • Respect page and pageSize parameters

  • Implement pagination UI or auto-scroll loading

  • Cache recent pages where possible to reduce API calls

---

6. Monitoring & Logging

• Log all outgoing API requests with:

  • Timestamp

  • Endpoint

  • Response status

  • Any error messages received

• This helps in debugging user issues and diagnosing performance bottlenecks.

---

7. Avoid Over-fetching

• Fetch data only when needed (e.g., avoid calling /get-routes on every page load).

• Use local state caching, revalidation, or SWR-style hooks for React apps.

---

8. Prepare for Changes

• While current endpoints do not include version prefixes, breaking changes (when introduced) will be versioned via the base URL, e.g.:

  https://api.reveel.id/v2/

• Stay subscribed to dev notifications and changelogs if provided.

---

9. Content-Type Issues

To avoid incorrect HTML responses:

• Always set the Accept: application/json header.

• Never omit the Content-Type: application/json header for POST/PUT/DELETE.

• Add logic to detect unexpected content types in responses.

---

10. Security Considerations

• Throttle requests per user or per IP to prevent abuse.

• Never log sensitive data like private keys or full API keys.

• If integrating wallets, validate addresses and perform checks against phishing or scam lists.