API versioning and lifecycle

The fulfillmenttools 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 General Availability (GA) and are marked as such. Additionally, fulfillmenttools may deprecate certain functionality in the API.

Consider the following example:

REST API

'/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 GA. However, the description field is still under development and may change. When working with the facility endpoint, ensure that the information provided in the description field isn't integrated into any mission-critical components that might be sensitive to changes.

GraphQL API

Lifecycle overview

Lifecycle state	Flag	Definition	SLAs	Breaking changes	Change notifications	Safe to use?
Alpha	Yes	In early-stage development, it might not be fully functional, unavailable at times, and could be removed without warning.	No	Common (both semantic and syntactic)	No notifications.	Recommended to contact fulfillmenttools first.
Beta	Yes	In late-stage development available for public testing. Functionality exists, but is unavailable at times, and could be removed without warning.	No	Rare	No later than two weeks before breaking changes.	Recommended to contact fulfillmenttools first.
GA	No	Production-ready and stable.	Yes	No	// Does this mean yes?	Yes
Deprecated	Yes	Replaced by new endpoints. Only removed when its no longer in use.	Yes (if previously GA)	No (if previously GA)	// Does this mean yes?	It will still work, but you should use the recommended new endpoint.

Enum handling

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

REST

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

GraphQL

However, the tooling around this use of enumerations varies. A code generator will most likely produce enums that can't 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.