Skip to main content

API Versioning

The Rivegen API uses URL-based versioning.

Current Version​

The current API version is v1, accessible at:

https://api.rivegen.com/api/v1/

For convenience, endpoints are also available at /api/ (which defaults to v1).

Version Format​

Version numbers follow semantic versioning principles:

  • Major versions (v1, v2) - Breaking changes
  • Minor versions - Backward-compatible additions
  • Patch versions - Bug fixes (transparent to API consumers)

Deprecation Policy​

When an endpoint or feature is deprecated:

  1. A deprecation notice will be included in the response headers
  2. Documentation will indicate the deprecation date and replacement endpoint
  3. Deprecated endpoints remain functional for at least 6 months
  4. Breaking changes are communicated at least 3 months in advance

Example Deprecation Header​

X-API-Deprecated: true
X-API-Deprecation-Date: 2024-07-15
X-API-Replacement: /api/v2/rivers/{river_id}

Checking API Version​

Include the API version in requests:

curl -X GET "https://api.rivegen.com/api/v1/rivers" \
  -H "Authorization: Bearer <token>"

Migrating Between Versions​

When upgrading to a new major version:

  1. Review the Changelog for breaking changes
  2. Test your integration against the new version in a staging environment
  3. Update your API client to use the new version URL
  4. Update request/response handling for any schema changes

See Also​