Versioning & Stability
What the Starship API guarantees won't change, how we handle breaking changes, and how to future-proof your integration
Versioning & Stability
The Starship API is versioned at the URL path (/api/v1/*). We treat that v1 as a stability contract: additions are fine, breaking changes are not.
What's stable (versioned under v1)
The following will not change without a new API version:
| Contract | Example |
|---|---|
| Endpoint paths | GET /api/v1/products, POST /api/v1/orders |
| Request body field names and types | product_id stays an integer; amount stays a decimal string |
| Response body field names and types | order.status stays a string enum |
| Error envelope shape | { error: { name, code, message, messages? } } |
| Error code strings | E_VALIDATION_FAILURE keeps that exact spelling |
| Auth headers | X-API-Key, X-API-Secret, X-Signature, Idempotency-Key keep their names |
| HMAC canonical-string format | 5-line algorithm documented in Request Headers |
| Webhook event envelope | { event_id, event_type, created_at, data } |
| Webhook signing algorithm | HMAC-SHA256 over timestamp + "." + body |
What may evolve (additive changes)
These changes can land in v1 at any time and are not considered breaking:
| Change | Example |
|---|---|
| New endpoints | POST /api/v1/orders/simulate (planned, feature-flagged off) |
| New optional request fields | Adding customer_info.phone — existing callers continue to work |
| New response fields | New key appears in JSON; your parser must ignore unknown keys |
| New enum values | New order.sub_status values — treat unknown as informational |
| New webhook events | order.refunded might appear; unsubscribe or subscribe at will |
| New error codes within a 4xx class | Always handle unknown codes by class (4xx, 5xx) |
| Stricter validation on a field already rejected today | Behaviors that were already error paths may tighten |
Write your integration to accept unknown enum values and unknown response keys without erroring. This is the single most effective investment in forward compatibility.
Ignore-unknown parsing. Prefer parsers like Go's json.Unmarshal into a struct, which ignores unknown keys by default. Avoid strict parsers that reject on unrecognized fields unless you plan to update your client within a day of each additive change we ship.
What counts as a breaking change
These would only happen in a new API version (v2):
- Removing an endpoint or making it return 410 Gone
- Removing or renaming a request/response field
- Changing a field's type (string → integer, etc.)
- Changing the HMAC algorithm or canonical-string format
- Restricting an enum to a smaller value set
- Moving required/optional status of a field (required → optional is additive; optional → required is breaking)
We don't do these in v1. If we need to, we version.
How breaking changes are announced
If we ship a v2:
- 30-day advance notice via email to all active API clients and a banner on starshiprewards.com
v1andv2run in parallel for at least 12 months — you migrate on your schedule, not ours- Sandbox-first:
v2lands on sandbox first, with at least 4 weeks of soak before production - Changelog entry in the Changelog (placeholder — real changelog page coming) with a side-by-side migration guide
- Per-endpoint deprecation warnings via a
Deprecationresponse header onv1endpoints during the overlap window
How to future-proof your integration
Lock your client to v1 explicitly
Build all URLs from a starship.v1.products.list() style helper that encapsulates the version. When v2 lands, only that helper changes.
Parse responses tolerantly
Unknown keys → ignore. Unknown enum values → log + fall back to a sensible default. Missing optional fields → zero-value.
Branch on error.code, never error.message
Messages may be re-worded for clarity. Codes are stable.
Subscribe only to webhook events you use
If you're not acting on order.pending, don't subscribe. Fewer events means fewer things to update when we add new ones.
Subscribe to changelog notifications
Your Starship contact will add you to the release-notes mailing list on request. Don't rely on implicit updates.
Long-term stability commitments
- The current
v1will not be end-of-life'd before mid-2028, barring a security incident requiring emergency migration. - There is no planned
v2as of this writing. - We do not silently change behavior of
v1endpoints. If you see an unexplained response shift, contact support — it's almost certainly a bug, not a change.
Reporting stability issues
If you find a breaking change that slipped through: email hello@rocketincentive.com with:
- The endpoint and date/time you observed the change
- The request and response you expected vs. got
- Your API key prefix (first 8 characters; never the full key)
We treat silent stability breaks as P1 incidents and fix them — not as a feature rollout.
Next
You've finished the Getting Started path. From here, the natural next reads are:
- Core Concepts — mental models for the API's behavior
- Authentication — deeper dive on HMAC and key rotation
- Reference Data — the enum/error/header references you'll return to