📘

NOTICE TO BETA USERS (That's You)

The API endpoints, as well as this documentation, is being provided to you as part of an early access / beta program. The goal of this beta is to collect feedback and make further improvements; therefore, (please, please please) DO NOT build any critical workflows or integrations based on the current state of our APIs, because there is a good chance that we will be introduce changes that will break your script/application/integration. Again - and we cannot emphasize this enough - these APIs are going to change, so treat anything built on top of them as likely throwaway work.

Rest API

Our versions in REST take the format of major.minor.patch. Major versions are the most important, and are used in our endpoint url's ex.test-cluster.openraven.io/api/{service-name}/{major-version}/{rest-of-url}.

Major versions are incremented when breaking changes are made. Breaking Changes are defined as:

• Adding or modifying input validation for an API
• Changing an existing input to be required. Adding a new input that is required.
• Adjusting the data type of existing fields
• Renaming fields or endpoints without redirects or maintenance of old alias
• Removing fields or endpoints
• When error codes are removed. Note, consumers of our API’s should only depend on error codes or HTTP response codes for control flow. Messages will be modified without a major version bump.

Minor versions are incremented when:

• New endpoints are added
• New fields are added
• When new error codes are added for an endpoint.

Patch versions are incremented when:

• Bug fixes are made

Types of Major Versions

1. Regular versions are stable according to our Deprecation Schedule
2. Beta versions are for new and emerging features in beta. These should not be used in production by customers because they are subject to change. Sometimes beta features will need additional manual enablement through helmfile feature flags before they are available in a cluster. In these cases, you will need to contact Customer Success to enable the feature.

Deprecation Schedule

After we do major API version bumps we will maintain the previous API version for at least 6 months.

GraphQL API

Our GraphQL API's have a "version" that is purely there to demarcate changes. Deprecation will be marked with the @deprecated directive with the following format:

sampleField @deprecated(
  reason: "Deprecated: v2.0.0
           EOL: 04/21/2023
           [Explanation]"
           )

Beta types or fields will be marked with the @beta directive.