API versioning & lifecycle

The fulfillmenttools Application Programming Interface (API) is versionless. This means the API evolves in a backward-compatible way. The following changes are considered backward-compatible:

Adding new API resources.
Adding new optional request parameters to existing API methods.
Adding new properties to existing API responses.
Changing the order of properties in existing API responses.
Adding values to enums (see Enum handling).

All endpoints, fields, and types in the fulfillmenttools APIs have a lifecycle ranging from Alpha to Beta to GA (Generally Available). Additionally, fulfillmenttools may deprecate certain functionality in the API.

Endpoints, types, fields, or features are marked by their release lifecycle. These are included as flags (see details in the corresponding sections). Consider the following example:

'/api/facilities/{facilityId}':
  get:
    operationId: getFacility
    summary: Get a facility with the given ID
    x-fft-api-lifecycle: ga
    responses:
      '200':
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Facility'

components:
  schemas:
    Facility:
      properties:
        id:
          type: string
          x-fft-api-lifecycle: ga
        description:
          type: string
          x-fft-api-lifecycle: alpha

In this case, the facility endpoint and entity are both generally available. However, the description field is still under construction and may change. When working with the facility endpoint, ensure that the information provided in the description field is not integrated into any mission-critical components that may be sensitive to changes.

In GraphQL, lifecycle information is implemented via schema directives. Schema directives, except for @deprecated, are not fetched during introspection. It is recommended to manually fetch the latest schema from the fulfillmenttools API Hub.

type Query {
  facility(id: String!): Facility @FFTMetadata(lifecycle = GA)
  listings: ListingConnection @FFTMetadata(lifecycle = GA)
}

type Facility @FFTMetadata(lifecycle = BETA) {
  id: ID! @FFTMetadata(lifecycle = GA)
  name: String! @FFTMetadata(lifecycle = GA)
  description: String! @FFTMetadata(lifecycle = ALPHA)

  listings: ListingConnection @semanticNonNull @FFTMetadata(lifecycle = BETA)
}

type ListingsConnection @FFTMetadata(lifecycle = GA) {
  edges: [ListingEdge] @semanticNonNull(levels = [0,1]) @FFTMetadata(lifecycle = GA)
}

The above example shows a typical case for mixed lifecycle flags in the fulfillmenttools GraphQL schema. Querying a facility and its id and name can be achieved using GA fields, which are fully covered under the fulfillmenttools SLAs. The same holds for listings, including filters like the facilityRef of the listing. However, querying all listings in a facility using Facility.listings, a non-GA field, is not covered under the SLAs. Additionally, the description field is still under construction and may change. When working with the facility endpoint, ensure that the information provided in the description field is not integrated into any mission-critical components that may be sensitive to changes.

Lifecycle overview

Lifecycle State

SLAs

Breaking Changes

Change Notifications

Alpha

Common

No notifications

Beta

Rarely

No later than two weeks before breaking changes

Yes

Deprecated

Yes (if previously GA)

No (if previously GA)

Alpha

Alpha endpoints are currently in development and might not be fully functional. Therefore, breaking changes (both semantic and syntactic) are common. These endpoints can be changed without communication. Additionally, Alpha endpoints are not contained in the fulfillmenttools SLAs.

Clients interested in using endpoints marked with the Alpha tag should contact fulfillmenttools.

Beta

Endpoints with the Beta lifecycle state are more mature but still under active development. fulfillmenttools tries to prevent breaking changes. Nevertheless, breaking changes are possible in rare cases. Functionality exists at these endpoints, but these are not covered in the fulfillmenttools SLAs. Breaking changes are communicated to clients two weeks before the change.

Clients interested in using endpoints marked with the Beta tag should contact fulfillmenttools.

GA (General Availability)

Endpoints without a lifecycle flag are production-ready, stable, and considered Generally Available (GA). These endpoints are served within the fulfillmenttools SLAs.

Deprecated

In some cases, fulfillmenttools might deprecate endpoints or attributes. Deprecated endpoints contain hints to new endpoints, replacing their functionality or providing a newer feature version. fulfillmenttools monitors deprecated endpoints to ensure functionality is only removed when it is no longer in use. Deprecated endpoints are still served within the fulfillmenttools SLAs if they had previously been GA.

Breaking changes

When an endpoint is under active development (e.g., marked as Alpha or Beta), fulfillmenttools might change its semantic or syntactic behavior. If an element has an Alpha or Beta flag, this indicates that:

The endpoint, type, or field might be subject to breaking changes.
It might not be available at all times.
It could be removed without specific warning.
It does not fall under the fulfillmenttools SLA regulations.

Enum handling

The fulfillmenttools schemas use many enums, for example, for status use. Adding a value to an enum is considered a nonbreaking change:

OrderStatus:
  type: "string"
  enum:
    - "OPEN"
    - "CANCELLED"
    - "LOCKED"
+   - "CLOSED"

However, the tooling around this use of enumerations varies. A code generator will most likely produce enums that cannot contain values different from the one described. When handling enums, the recommended practice is to map unknown enum values to recognized values or to values that yield an error.

Last updated 4 days ago