API Change Log

You must create a new major version of your API in the following scenarios, as they represent breaking changes:

• Removing an existing endpoint or resource: If an API endpoint that consumers are actively using is completely removed, it will break their applications.

• Renaming an existing endpoint or resource: Changing the URL path of an endpoint (e.g., /users to /customers) will break existing calls.

• Changing the request method for an endpoint: If an endpoint previously accepted GET and now only accepts POST, it’s a breaking change.

• Modifying the structure of a request body:

  • Removing a required field.

  • Renaming a field.

  • Changing the data type of a field (e.g., string to integer).

  • Changing the expected format of a field (e.g., date format).

• Modifying the structure of a response body:

  • Removing a field that consumers rely on.

  • Renaming a field.

  • Changing the data type of an existing field.

  • Changing the meaning or values of an enum field.

• Changing authentication or authorization mechanisms: If the way consumers authenticate or authorize their requests changes fundamentally (e.g., from API keys to OAuth 2.0, or different scope requirements).

• Altering error codes or error response structures: If the status codes or the format of error messages change, client applications might fail to parse errors correctly.

• Introducing new mandatory headers or query parameters: If a previously optional header or parameter becomes mandatory for existing endpoints.

• Reducing rate limits significantly without prior notice: While not a structural change, a drastic reduction in rate limits can break applications that rely on higher throughput.

• Changing the underlying data model in a way that affects existing fields: Even if field names remain the same, if their semantics or constraints change in a way that breaks existing logic.