Modulify
Dashboard

Versioning

What the v1 in every address promises, what can change without notice, and how to write code that keeps working.

On this page

Every address starts with /v1. That number is a promise about what stays the same, so code written today keeps working as Modulify grows.

What v1 keeps

Within v1:

  • Methods are not removed or renamed. A method name that works today keeps working.
  • Arguments are not removed, renamed or retyped. An argument that takes a string today takes a string tomorrow.
  • Required arguments stay the same. A method never starts requiring an argument it did not require before.
  • The envelope stays the same. Every answer keeps success, message, data, code and version, plus count on lists.
  • Status codes keep their meaning. A 401 is always the token, a 429 always means slow down.

Anything that would break one of these comes as a new version beside v1, not as a change to it.

What can change at any time

These are additions, so they arrive without a new version:

  • New methods. The catalog grows as Modulify does. GET /v1/tools and the OpenAPI description always list the current set.
  • New optional arguments. Leaving them out keeps the old behaviour.
  • New fields in data. An answer can carry more than it did.
  • New values in a list of choices that an answer reports, such as a new publish step or a new event type in get_job.
  • Wording. message is written for people. Do not match on its exact text. Branch on code, and on fields such as data.reason where a method provides them.
  • Limits. Numbers such as the per-minute budget and queue sizes can be raised or lowered by Modulify. Read them from the X-RateLimit headers and from the answers rather than hard-coding them.

Write code that lasts

  • Ignore fields you do not recognise rather than failing on them.
  • Treat an unknown value in a list of choices as "something else" rather than an error.
  • Branch on status codes and named fields, never on message text.
  • Read limits at run time.

How changes are announced

New methods, new arguments and anything else a developer should know about appear in the changelog. Each method's page always describes its current behaviour.

Next