Overview#
This document outlines the API versioning strategy for the I'm Guide API. The versioning approach ensures backward compatibility while allowing improvements and new features.Current Version#
API Version: 1.2.0#
Release Date: Oct 29, 2024#
Enhancements:: Version 1.2.x introduces enhanced trip configuration, user-specific custom trip management, and new trip creation options, including TAT preset routes and non-AI functionalities.
Changelog#
Focused on trip configuration and TAT route creation.
| Method | Endpoint Slug | Version | Description |
|---|
| GET | /trips/v1/config/province | 1.0.0 | Get provinces list |
| GET | /trips/v1/config/place-keyword | 1.0.0 | Get place keyword categories |
| GET | /trips/v1/custom/me | 1.0.0 | Get created custom trips specific user. |
| GET | /trips/v1/custom/me/:id/detail | 1.0.0 | Get created custom trips detail |
| POST | /trips/v1/custom/preset | 1.0.0 | endpoint for create custom trip with none ai function |
| POST | /trips/v1/custom/tat-route | 1.0.0 | endpoint for create trip with tat perset route |
Versioning Strategy#
URL Versioning#
Versioning is implemented in the URL path to ensure clarity for users. For example: /trips/v1/place or /trips/v2/customMajor versions are indicated by /v1/, /v2/, etc., and will be incremented when breaking changes are introduced.Types of Versioning#
Major Versioning#
A major version is released when there are breaking changes that might disrupt clients using the current API version. For instance, removing or renaming endpoints or parameters.Minor Versioning#
Minor versions are introduced when there are new backward-compatible features or enhancements added to existing endpoints.Patch Versioning#
Patch versions are used for small changes such as bug fixes or minor updates that do not affect the API’s functionality.Example Scenarios#
| Type | Example Scenario |
|---|
| Major | Removing or renaming /trips/v1 endpoints in /trips/v2. |
| Minor | Adding new optional parameters to /trips/v1/place. |
| Patch | Bug fixes or performance optimizations that don’t change API responses. |
Deprecation Policy#
Deprecation Notice: When an API endpoint is deprecated, it will be clearly marked as such in the documentation. Clients will also receive deprecation notices in the API responses to ensure they are informed about the upcoming changes.Deprecation Timeline: Deprecated endpoints will remain active for at least 6 months after the deprecation notice. This gives clients adequate time to transition to newer versions or alternative endpoints.Error Codes & Handling#
When versioning impacts the API's behavior, relevant error codes will be updated. For instance, calling an unsupported version of an endpoint may result in a 400 Bad Request or a 500 Internal Server Error.Example#
{
"statusCode": 400,
"error": "Bad Request",
"message": "Version not supported"
}
Backward Compatibility and Breaking Changes#
Maintaining backward compatibility is crucial for minimizing disruption to clients. The API will only introduce breaking changes in major version updates. Minor and patch versions are always backward compatible.API Version Lifecycle#
Active Support#
Mobile app APIs will continue to receive new features, bug fixes, and optimizations during the active support phase.Deprecation Policy#
Deprecated APIs will remain available for 6 months after notice is given. After this period, they will be deactivated, and mobile apps must migrate to the newer version.EOL (End-of-Life)#
APIs that have reached the end of their life cycle will be permanently removed, and any requests made to these APIs will return a 410 Gone error.