search

camaraproject / OTPValidation

Repository to describe, develop, document and test the OTP Validation API family
https://wiki.camaraproject.org/display/CAM/OTPValidation
Apache License 2.0
6 stars 14 forks source link

Enhancements to One Time Password SMS API for Better Usability and Compliance #42

Closed ajamous closed 6 months ago

ajamous commented 10 months ago

Overview

This issue outlines a series of proposed enhancements to the One Time Password SMS API to improve its usability, security, and compliance. The goal is to provide a clearer, more robust, and developer-friendly API that aligns with best practices and industry standards.

Below we compare the current API specification with the suggested enhancements by providing concrete examples for each for your review:

  1. Performance Metrics:

    • Current: No performance metrics are defined in the documentation.
    • Suggestion: Document expected performance metrics.
    • Example: Add to the documentation: "The API is designed to handle up to 10,000 requests per minute with an average latency of 500 ms."

  2. Endpoint Descriptions:

    • Current: Endpoint descriptions are basic, with no mention of rate limits.
    • Suggestion: Add details about rate limits to endpoint descriptions.
    • Example: Add to /send-code endpoint description: "Rate limited to 100 requests per hour per phone number."

  3. Error Handling:

    • Current: Generic error messages, e.g., "message": "Client specified an invalid argument, request body or query param".
    • Suggestion: Provide specific error messages and troubleshooting steps.
    • Example: Change to "message": "Invalid 'phoneNumber' format. Ensure it is in E.164 format, including the '+' sign and country code."

  4. Security Schemes:

    • Current: OAuth2 security scheme with no details on token algorithm or lifecycle.
    • Suggestion: Specify token algorithm and lifecycle best practices.
    • Example: In securitySchemes, add "algorithm": "RS256" and in the description: "Tokens have a 60-minute lifetime before expiration."

  5. Request and Response Bodies:

    • Current: Message maxLength: 160
    • Suggestion: Handle multi-part messages internally.
    • Example: Update the API to accept "maxLength": 640, with documentation stating: "Messages will be automatically segmented and reassembled."

  6. Rate Limiting and Quotas:

    • Current: No explicit rate limiting headers or documentation.
    • Suggestion: Define and document rate limits, include headers in responses.
    • Example: Include in response headers X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

  7. Webhooks for Asynchronous Operations:

    • Current: No webhook support.
    • Suggestion: Implement webhooks for status updates.
    • Example: Add a webhook endpoint in the documentation for status updates, e.g., "webhookUrl": "https://clientapp.com/otp-delivery-status".

  8. Localization and Internationalization:

    • Current: No support for multiple languages in the Message schema.
    • Suggestion: Support multiple languages.
    • Example: Add "locale": "en-US" in the SendCodeBody schema, with a note: "Locale parameter sets the language for OTP messages."

  9. Testing and Sandbox Environment:

    • Current: No separate sandbox environment URL provided.
    • Suggestion: Provide a sandbox environment URL.
    • Example: Add a sandbox URL like https://api.sandbox.example.com/one-time-password-sms/v0 for testing.

  10. Monitoring and Analytics:

    • Current: No endpoints for monitoring or analytics.
    • Suggestion: Add monitoring and analytics capabilities.
    • Example: Include an endpoint GET /analytics/otp-usage to fetch usage statistics.

  11. Compliance and Regulation:

    • Current: No mention of compliance with privacy regulations.
    • Suggestion: Add compliance features and documentation.
    • Example: Include a field in the request schema for user consent: "userConsent": true, with a note on GDPR compliance.

The above examples highlight the difference between the current state of the API and how each suggested improvement could be articulated within the API documentation or functionality.

DT-DawidWroblewski commented 8 months ago

Hi @ajamous !

Can you join our community call (25/01/2024, Thursday, 8:30 GMT+1), so we can discuss this issue?

MS Teams link

Thx! David

DT-DawidWroblewski commented 6 months ago

Hi!

closing this issue.

@ajamous if more concerns are coming in future and this issue becomes relevant - we can reopen it.

Thx!