Versioning and deprecation

Omit the header and you get the version pinned to your account at first use. Pin it explicitly in production.

What we may change without a version bump

• Adding a new endpoint, resource, or optional parameter

• Adding a field to a response

• Adding a value to a non-exhaustive enum — publication_type, tone, citation styles, subjects. status, depth, and error.type are exhaustive and will not gain values without a version date

• Improving answer quality within a depth

Write clients that tolerate unknown fields and unknown enum values.

What requires a new version date

• Removing or renaming a field or parameter

• Changing a type, default, or required-ness

• Changing pagination, error shapes, or status semantics

Deprecation policy

• Each version date is supported for at least 12 months after its successor ships

• Removals get 90 days notice, announced in the changelog and emailed to organization owners

• Deprecated endpoints return a SciSpace-Deprecation: <sunset-date> response header for the whole notice period

• New version dates are published at most quarterly

Related

conventions · changelog