Skip to main content

WeInc API versioning and deprecation policy

What you can rely on when you integrate against https://weinc-coastside.vercel.app/api/v1.

Versioning

  • The version is part of the URL path: /api/v1.
  • Within a version we only add: new endpoints, new optional parameters, new response fields. Existing fields, types and status codes do not change.
  • Breaking changes ship as a new path version (/api/v2). The previous version keeps working through the deprecation window.

How deprecation is signalled

When an endpoint or a whole version is scheduled for retirement, every response from it carries:

  • Deprecation: @<unix timestamp> (RFC 9745), the date the deprecation was announced.
  • Sunset: <HTTP date> (RFC 8594), the date after which it may stop responding.
  • Link: <https://weinc-coastside.vercel.app/developers/versioning>; rel="deprecation", pointing to this page.

Deprecated operations are also flagged deprecated: true in the OpenAPI document at /openapi.json.

Timeline

  • At least 12 months between the Deprecation announcement and the Sunset date for a version.
  • At least 6 months for a single endpoint or field.
  • Current status: nothing is deprecated. v1 is the only version.

Contact

Questions about a change: hey@we.inc. Back to the developer portal.