Skip to main content

Versioning

The version is in the path: https://api.getreeds.co/shipping/v1. This page explains what changes inside v1 and what doesn't.

Changes that don't need a new version​

Reeds adds the following to v1 without a new version:

  • new fields in responses and webhook payloads
  • new event types
  • new values for existing fields, such as a new delivery status or a new service
  • new optional request fields and new endpoints

Write your client to cope:

  • Ignore unknown fields. Don't fail when a response has a field you don't know.
  • Tolerate unknown enum values. Give every switch on a status or type a default branch.
  • Ignore unknown webhook event types. Reply 200 and move on.
switch (delivery.status) {
  case 'delivered': markDelivered(delivery); break;
  case 'cancelled': markCancelled(delivery); break;
  default: markInProgress(delivery); // includes statuses Reeds adds later
}

Breaking changes​

A change that could break a correct client, such as removing a field or changing its meaning, goes to a new version, /v2.

  • /v1 and /v2 run side by side for six months.
  • Reeds announces the change on the changelog and by email to every account with live credentials.
  • You migrate at your own pace within that window.

Stay informed​

  • Read the changelog. Every public change has an entry.
  • Make sure the email address on your account is one that someone reads.

Next steps​