Updates API
Suggestion for Endpoint Versioning
To avoid issues for users when updating services or endpoints, let’s adopt versioning as a standard practice:
Create a New Version: For significant changes, such as contract updates, add a new endpoint (e.g., /api/v2/users) while keeping the previous version functional.
Document and Communicate: Clearly explain the differences between versions and notify users in advance about any changes or deprecations.
Test All Versions: Ensure every version works as expected.
This approach ensures stability for current API users, simplifies the adoption of updates, and builds trust with consumers.
2 Replies
rival-blackOP•3mo ago
@Marco Aurelio PSC
Example of Issues with API Changes
The calendar event creation API has undergone changes that are causing significant disruptions:
1. Inconsistent time zone: The time zone no longer respects UTC-3, which may misalign previously configured schedules.
2. New required parameters: The parameters
These changes are breaking existing solutions and causing functionalities to stop working, often without prior notice.
Suggestions for Improvement: - Preserve current functionality: Changes to default behavior (like the time zone) should be introduced in a new API version to avoid impacting existing users.
- Flexible parameters: Make parameters optional where applicable. For example, allow the use of
- Communicate changes: Notify users in advance about modifications, giving them time to adapt.
These practices help minimize disruptions and maintain trust with API consumers.
The calendar event creation API has undergone changes that are causing significant disruptions:
1. Inconsistent time zone: The time zone no longer respects UTC-3, which may misalign previously configured schedules.
2. New required parameters: The parameters
durationHour and durationMinutes were added as mandatory, forcing users to provide both even when it would make sense to use just one of them.These changes are breaking existing solutions and causing functionalities to stop working, often without prior notice.
Suggestions for Improvement: - Preserve current functionality: Changes to default behavior (like the time zone) should be introduced in a new API version to avoid impacting existing users.
- Flexible parameters: Make parameters optional where applicable. For example, allow the use of
durationHour or durationMinutes instead of requiring both.- Communicate changes: Notify users in advance about modifications, giving them time to adapt.
These practices help minimize disruptions and maintain trust with API consumers.
judicial-coral•3mo ago
thanks for sharing these @brenosilverio - sent it to the team.