Skip to content
PaalChat Docs

Build and operate

Versioning and deprecations

What may change inside /v1, how you hear about it, and how a /v2 would run alongside.

.md

In a nutshell

Inside /v1 PaalChat only adds - new endpoints, optional fields, response fields, events and error codes. Anything that would break you waits for /v2. Deprecated endpoints keep working for at least six months and say so in Deprecation and Sunset headers.

Every response carries X-PaalChat-API-Version: v1. The version is in the URL (/api/v1/...), so nothing changes under you without a new URL.

What may change inside v1

These are not breaking, and may happen at any time - build your client to tolerate them:

  • New endpoints, and new optional request fields or query parameters.
  • New fields in responses and in callback data (ignore fields you don't know).
  • New callback events (endpoints only get the events they subscribe to - or all, if they subscribe to none, so ignore event names you don't know).
  • New error.code values (handle unknown codes by their HTTP status).
  • New values in documented open lists - for example message type, a template's status, or whatsapp.connection events.
  • Longer limits (larger maximum lengths, higher rate limits).

What waits for a new version

These would break existing clients, so they only happen in /v2:

  • Removing or renaming an endpoint, a field or an event.
  • Changing a field's type or meaning, or making an optional field required.
  • Changing the error envelope, authentication, or callback signing.
  • Narrowing what is accepted (shorter limits, stricter formats) where valid calls would start failing.

Deprecations

When something in /v1 is to go away (because /v2 has a better way):

  1. It is announced in the changelog and marked deprecated in the API reference.
  2. Its responses carry Deprecation (when it was deprecated), Sunset (when it stops working) and a Link to the migration notes. Log these headers in your client.
  3. It keeps working for at least six months after the announcement.

A new version

/v2 would run alongside /v1, with the same keys, businesses and data - you move endpoint by endpoint. /v1 stays available for at least twelve months after /v2 is released, and its sunset date is announced at least six months ahead.