Best Practices

Overview

• Follow these practices to make your integration secure, reliable, and easy to maintain when using WAYN’s Verify / Reach / Notify APIs.

Security & Transport

• Use secure connections only (TLS 1.3 recommended) so data between your systems and WAYN is protected.
• Protect credentials: store clientId / clientSecret in environment variables or a secrets vault — never commit them to source control.

Payloads & Compatibility

• Send JSON encoded as UTF-8 and set Content-Type: application/json.
• Allow unknown or new fields (do not strictly reject payloads with extra properties) so your client remains compatible when the API adds non-breaking fields.

Authentication & Tokens

• Use OAuth2 Client Credentials to obtain a JWT and include Authorization: Bearer <token> on protected calls.
• Tokens expire (typically ~1 hour). Implement automatic token refresh logic before expiry.

Rate Limits & Retries

• Respect rate limits. If you receive a 429 response, back off and retry with exponential backoff (jitter helps avoid thundering herds).
• Retry transient server errors (e.g., 503) with a limited number of attempts and exponential backoff.

Error Handling & Troubleshooting

• Parse error responses and show friendly messages to operators. Use the returned CorrelationId when contacting support to speed up investigation.
• Distinguish between client errors (4xx) and transient server errors (5xx) to decide whether to retry.

Environments & Testing

• Test fully in the staging or sandbox environment before switching to production.
• Validate integration flows with realistic test data where possible.

Data & Time Handling

• Treat timestamps from WAYN as UTC. Convert to local time on the client only for display purposes.

Operational Hygiene

• Include a descriptive User-Agent header with application name and version (example: MyApp/1.2 (WAYN Integration)).
• Log requests, responses, and correlation IDs safely (never log secrets) to help debug issues.

Maintenance & Updates

• Keep your client libraries and integration up to date with the latest documentation and SDKs.
• Monitor deprecation notices and migrate before old endpoints are removed.

Additional Tips

• Limit batch sizes per API guidance (e.g., up to 100 mobile numbers for batch endpoints).
• For Notify attachments, respect documented limits (number and size) to avoid rejections.
• Document your internal mapping, error handling, and retry behavior for onboarding and maintenance.

Need Help?

• When reporting an issue, include request samples, timestamps, and the CorrelationId returned by the API so support can triage quickly.