API and SDK Versioning

OpenAPI Document Versioning

All Intersight OpenAPI documents are versioned. When Intersight services are updated to support a new capability, the version of the Intersight OpenAPI document is changed and the corresponding document is published. The updated OpenAPI document may include new API endpoints, API schemas, security schemes and other OpenAPI constructs. The version of the Intersight OpenAPI document is set in the info.version field. The OpenAPI document also specifies the schema version in the openapi field to indicate the conformance with a particular version of the OpenAPI specification.

openapi: 3.0.2
info:
  title: Cisco Intersight
  version: 1.0.0

SDK Version

When a new Intersight OpenAPI document version is published, the Intersight SDKs are also generated and published at the same time.

API Backward-compatibility

API backward-compatibility means an old API client can send a payload to a newer version of the Intersight software, and the older client can parse the server response without causing errors. However, an old client will not be able to access new API endpoints and new properties. The API major version is not changed when backward-compatible changes are deployed. If an API change breaks backward-compatibility, older API clients must be updated to send requests to the newer Intersight API.

List of Changes that Retain Backward-compatibility

Intersight API and SDK changes are mostly backward-compatible. You do not have to download the SDK every time a new version of the Intersight OpenAPI document is published. You can download the SDK when you want to access new endpoints or new properties.

The following API changes are considered backward-compatible:

  • Adding a new API endpoint (in the OpenAPI paths section).
  • Adding a new schema (in the components section).
  • Adding a new optional property to an existing schema.
  • Adding a new optional request parameter.
  • Adding a new security scheme or a new OAuth2 scope.
  • Adding a new HTTP verb (e.g. POST, PUT, DELETE) to an existing API endpoint.
  • Adding a new content type in an existing API endpoint.
  • Adding a new optional HTTP header.
  • Adding a new enum value.
  • Adding a new HTTP error status code.
  • Adding or updating documentation keywords such as description, title or tags.
  • Adding a new link in the links section.

Additional Properties

Additional properties are properties that are present in the payload but not explicitly declared in the Intersight OpenAPI document. API clients must be prepared to receive additional properties in the payload and gracefully handle these undeclared properties. By default, all schemas present in the Intersight OpenAPI document support additional properties, using the keyword additionalProperties implicitly set to true. For instance, an API client may receive additional properties when the API server software is updated even though the client is still using an older version of the Intersight SDK.

List of Changes that Break Backward-compatibility

The following changes are considered to break backward-compatibility:

  • Removing an API endpoint.
  • Adding a new required request parameter.
  • Adding a new required property to an existing schema.
  • Removing or changing the type of a request parameter, or schema property.
  • Modifying or removing an enum value.

API Client Expectations

To correctly handle backward-compatible API changes, API clients are expected to implement the following behavior:

  • Clients must be prepared to accept additional properties in the response payload from the server.
  • Clients can send sparse payloads in the HTTP requests. Optional properties do not need to be present in the HTTP request body.

MOID Values

MOID values uniquely identify API resources. MOID values are guaranteed to be unique for a particular API endpoint, but not across API endpoints. Clients should not rely on MOIDs being unique across API endpoints.