## Versioned API Design Document: AcmeCorp Payments API **API Domain:** `https://payments.acmecorp.com` **Versioning Scheme:** URL path (v1, v2) **Resources to Version:** transactions, accounts, customers **Deprecation Window (Months):** 12 **1. Versioning Strategy and Rationale** * **Strategy:** URL Path Versioning * **Rationale:** * **Simplicity:** URL path versioning is straightforward to implement and understand. The version is explicitly part of the URL, making it easy for developers to locate and use the correct version. * **Discoverability:** The version is directly visible in the URL, aiding in API exploration and documentation. * **Caching:** URLs are cacheable. Different versions are treated as distinct resources, allowing for effective caching at various layers (e.g., CDNs). * **Ease of Routing:** Web servers and API gateways can easily route requests based on the URL path. * **Avoids Header Confusion:** Header-based versioning can sometimes conflict with standard HTTP headers or application-specific headers. * **Clear Semantics:** The URL explicitly identifies the version of the resource being accessed. **2. Supported Versions and Migration Path** * **Supported Versions:** v1, v2 * **Migration Path:** * New features and enhancements will be primarily introduced in the latest version (v2). * Older versions (v1) will receive bug fixes and security updates only for a defined period (migration grace period). * After the migration grace period, v1 will be deprecated and eventually decommissioned. * **Deprecation Notice:** A deprecation notice will be announced via email, documentation, and potentially a warning header in the API responses from the deprecated version, 12 months prior to full deprecation. **3. Endpoint Map by Version** | Resource | v1 Endpoint | v2 Endpoint | |----------------|-----------------------------------------------------------|-----------------------------------------------------------------| | Transactions | `https://payments.acmecorp.com/v1/transactions` | `https://payments.acmecorp.com/v2/transactions` | | Transactions | `https://payments.acmecorp.com/v1/transactions/{id}` | `https://payments.acmecorp.com/v2/transactions/{id}` | | Accounts | `https://payments.acmecorp.com/v1/accounts` | `https://payments.acmecorp.com/v2/accounts` | | Accounts | `https://payments.acmecorp.com/v1/accounts/{id}` | `https://payments.acmecorp.com/v2/accounts/{id}` | | Customers | `https://payments.acmecorp.com/v1/customers` | `https://payments.acmecorp.com/v2/customers` | | Customers | `https://payments.acmecorp.com/v1/customers/{id}` | `https://payments.acmecorp.com/v2/customers/{id}` | **4. Backward Compatibility and Deprecation Policy** * **Backward Compatibility:** * Efforts will be made to maintain backward compatibility within minor revisions of each version. For example, adding new optional fields to a response is considered backward compatible. * Breaking changes will only be introduced in new major versions (e.g., v2). * **Deprecation Policy:** * A minimum of 12 months' notice will be provided before completely removing a deprecated version. * Deprecation notices will be communicated through: * Email notifications to registered API users. * Announcements on the API documentation portal. * `Deprecation` header in the API responses for deprecated endpoints. The value of the header will be the date of deprecation. * During the deprecation period, the deprecated version will continue to function. **5. Resource Schemas** **5.1 Transactions** * **v1:** ```json { "transactionId": "string", "amount": "number", "currency": "string", "timestamp": "string", "status": "string", "accountId": "string" } ``` * **v2:** (Adds `description` and standardized `dateTime` format, also includes a `fees` field) ```json { "transactionId": "string", "amount": "number", "currency": "string", "dateTime": "string (ISO 8601)", "status": "string", "accountId": "string", "description": "string", "fees": "number" } ``` **5.2 Accounts** * **v1:** ```json { "accountId": "string", "accountName": "string", "accountType": "string", "balance": "number", "currency": "string" } ``` * **v2:** (Adds `createdDate` and `updatedDate` and standardized `dateTime` format. Replaced `accountType` with `accountCategory`) ```json { "accountId": "string", "accountName": "string", "accountCategory": "string", "balance": "number", "currency": "string", "createdDate": "string (ISO 8601)", "updatedDate": "string (ISO 8601)" } ``` **5.3 Customers** * **v1:** ```json { "customerId": "string", "firstName": "string", "lastName": "string", "email": "string" } ``` * **v2:** (Adds `phoneNumber` and `address` objects) ```json { "customerId": "string", "firstName": "string", "lastName": "string", "email": "string", "phoneNumber": "string", "address": { "street": "string", "city": "string", "state": "string", "zipCode": "string", "country": "string" } } ``` **6. Sample Requests and Responses** **6.1 Transactions** * **v1 - Request:** `GET https://payments.acmecorp.com/v1/transactions/123` * **v1 - Response:** ```json { "transactionId": "123", "amount": 100.00, "currency": "USD", "timestamp": "2023-10-26T10:00:00Z", "status": "COMPLETED", "accountId": "456" } ``` * **v2 - Request:** `GET https://payments.acmecorp.com/v2/transactions/123` * **v2 - Response:** ```json { "transactionId": "123", "amount": 100.00, "currency": "USD", "dateTime": "2023-10-26T10:00:00Z", "status": "COMPLETED", "accountId": "456", "description": "Payment for goods", "fees": 0.50 } ``` **6.2 Accounts** * **v1 - Request:** `GET https://payments.acmecorp.com/v1/accounts/456` * **v1 - Response:** ```json { "accountId": "456", "accountName": "My Checking Account", "accountType": "CHECKING", "balance": 5000.00, "currency": "USD" } ``` * **v2 - Request:** `GET https://payments.acmecorp.com/v2/accounts/456` * **v2 - Response:** ```json { "accountId": "456", "accountName": "My Checking Account", "accountCategory": "CHECKING", "balance": 5000.00, "currency": "USD", "createdDate": "2022-05-15T08:00:00Z", "updatedDate": "2023-10-26T10:00:00Z" } ``` **6.3 Customers** * **v1 - Request:** `GET https://payments.acmecorp.com/v1/customers/789` * **v1 - Response:** ```json { "customerId": "789", "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com" } ``` * **v2 - Request:** `GET https://payments.acmecorp.com/v2/customers/789` * **v2 - Response:** ```json { "customerId": "789", "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phoneNumber": "+15551234567", "address": { "street": "123 Main St", "city": "Anytown", "state": "CA", "zipCode": "91234", "country": "USA" } } ``` **7. Migration Guidance** 1. **Review the Release Notes:** Carefully review the release notes for v2 to understand the changes, including any breaking changes and new features. 2. **Identify Affected Endpoints:** Determine which endpoints in your application need to be updated to use v2. 3. **Update API Endpoint URLs:** Modify your application code to use the v2 endpoints (e.g., change `/v1/transactions` to `/v2/transactions`). 4. **Adapt to Schema Changes:** * **New Fields:** Handle any new fields added to the responses (e.g., `description` and `fees` in the `Transaction` resource). * **Renamed Fields:** Adapt your code to use the new field names (e.g. replace `accountType` with `accountCategory`). * **Data Type Changes:** Adjust your code to handle any data type changes. Ensure you’re sending `dateTime` fields using the correct ISO 8601 format. * **Address Changes:** If applicable, update code to handle address as a nested object. 5. **Test Thoroughly:** Thoroughly test your application after making the changes to ensure that it integrates correctly with v2. Pay particular attention to error handling and edge cases. 6. **Monitor Performance:** Monitor the performance of your application after the upgrade to ensure that the new version is performing as expected. 7. **Deprecation Awareness:** Keep track of the deprecation schedule for v1 and plan your migration accordingly to avoid disruptions. 8. **Rollout Strategy:** Consider a phased rollout to v2, gradually migrating different parts of your application to the new version. 9. **Support Resources:** Consult the API documentation and support resources for any questions or assistance during the migration process.