At Productboard, we're committed to maintaining both backward and future compatibility as much as possible. What does this mean for you? Essentially, we aim to make changes that you can adapt to smoothly, at your own pace, without causing disruptions to your workflow. Typically, we'll announce these backward-compatible changes after they're implemented. However, it's crucial for your application to be ready for certain types of changes that may occur without prior notice:
- New Kids on the Block: Expect the arrival of new endpoints and methods on existing ones.
- Expanding Horizons: We might add new fields in various scenarios:
- Fresh fields in responses.
- New optional request fields or parameters.
- The introduction of a new text value in existing fields.
- New enum values or polymorphic subtypes in responses, sent only when your system has indicated its readiness.
- Shuffling the Deck: The order of fields in responses may change.
- Optional Extras: Watch out for additional optional request headers.
- Size: There could be changes in the length of data within fields and overall response size.
- Message Makeover: Error messages might get a facelift. (Tip: Stick to HTTP response codes and error codes for business logic.)
- Fixing the Mix-Up: Corrections to HTTP response codes and error codes.
- Error Code Expansion: Introduction of new error codes.
In the rare event of a backward-incompatible change, we'll roll out a shiny new version of the API. Just remember, you'll need to specify the version using the X-Version header (right now, the only star of the show is version 1).
What We Expect from You
To keep our API lean and mean (and avoid unnecessary versions), we have a couple of asks:
- Go with the Flow: Use a standard JSON parsing library that isn't fussy about the order of elements.
- Embrace the Unknown: Make peace with ignoring unknown elements in response or callback payloads. This flexibility allows us to enhance the API by adding new fields without causing any hiccups for you.
Together, we can ensure that the Productboard API continues to evolve efficiently and effectively!