API-lifecycle

In this article, we will describe the lifecycle of our APIs.

1. Versioning

We decided to use semantic versioning. The version number is given in following format in endpoint URI:
• Production: https://api.mediaconnect.no/capi/v1/...
• Test: https://api-test.mediaconnect.no/capi/v1/ ...

1.1 Semantic versioning

Semantic versioning means:
• Major version: Any changes that are not compatible with previous version of API will require a new major version.
• Minior version: This include adding new endpoints, fields or other that are backwards compatible to the API.
• Patch: Small changes like fixing bugs and modify text description of APIs, endpoints, or fields.

1.2 API-lifecycle

The stages in API lifecycle are listed in chronological order below:

• Proposed: A endpoint is defined and will be implemented soon.
• In Test: The latest version of the endpoint is now ready for test and is available in our test environment.
• In Production: The latest version of the endpoint is now in production, and is available in our producation environment.
• Deprecated: The endpoint is now deprecated, and will be removed from our test and production environment in 180 days (6 months). Do not use this endpoint for future software development.
• Deprecated Warning: The endpoint has previously been deprecated and will be sunset soon. The endpoint will be removed in 30 days.
• Ready for sunset: The endpoint will be sunset and will not be usable after the sunset. The endpoint will be removed in 10 days.
• Sunset: The endpoint is now sunset. The endpoint is now not able to be used and has been removed from our test and production environment.

A endpoint may change from the stage "In producation" to "In Test" if it is changes in the endpoint for example a new field/enum has been added to the endpoint.

1.3 Information about release and deprecation

A new version of the API and documentation will normally be released on Thursday every other week. At the same time, we will inform upcoming deprecation of endpoints/fields in the API documentation.

1.4 Changelog

We have a webpage to show the changes on the API-documentation. You can see the changelog on Mediaconnect API changelog. The change log is updated at the same time as the API documentation.

2. How do Mediaconnect inform you

Mediaconnect will inform you by Statuspage or email.

2.1 Statuspage

Mediaconnect are using a platform called statuspage to inform our customer about operational information regarding APIs. We kindly request you to subscribe to messages from Statuspage.

2.2 Email

We will email the technical contact or main contact.

3. Backwards compatibility

The services will be regularly upgraded. Generally, this should not be an issue for the client. All existing elements will be present in new versions. New elements may be added. Your application may safely ignore new elements.

If there are major changes to a service, it will normally be developed as a new endpoint with the new / changed functionality. The old version will be available to other clients that are not upgraded to the latest version. New clients should always use the newest version.

Services may be dropped if there are no known clients using it or if the service is not compatible with changes to the core system. Client developers will be notified if this should happen by email.

The following changes are considered as backwards compatible.

3.1 Adding a new optional field to an endpoint in request.

Adding a new optional field to an endpoint in a request is considered as a backwards compatible change.

Example:
Mediaconnect may add a GLN number to support international standard, in additional to national organization number.

Request before adding a new optional field:

  "CompanyInfo": {
    "Companycode": 23467892
  }

Request after adding a new optional field:

  "CompanyInfo": {
    "Companycode": 23467892,
    "GLN": 7080001213916,
  }

3.2 Adding a new optional field to an endpoint in response.

Adding a new optional field to an endpoint in a response is considered as a backwards compatible change.

Example:
We may add a field that shows which communication channel the customers used to stop the delivery in Delivery Stop API. We may add “deliveryStopChannel” field to DeliveryStop object.

Response before adding a new field:

  "deliveryStops": {
      "id": 1,
      "product": "CO27409",
      "stopTime": 1561121761000,
      "stopEndTime": 1561985761000,
      "stopType": "temporary",
    }

Response after adding a new field:

  "deliveryStops": {
      "id": 1,
      "product": "CO27409",
      "stopTime": 1561121761000,
      "stopEndTime": 1561985761000,
      "stopType": "temporary",
      "deliveryStopChannel": "Email"
    }

3.3 Adding a new enum value to a field

We may add an enum value to request or a response.
For example, we may add a new enum value to the field paymentMethod to add new payment method. This type of change is considered as a backwards compatible change.

3.4 API fields – make it optional from required.

We may change the fields in APIs from required to optional, but not from optional to required.

4. Breaking changes

Breaking changes are changes that are not compatible with previous version of the API. This means there is a need for a major version.

4.1 Changing the name of the field and enum:

It is a breaking change if we change the name of the field or the enum.

Example:
The field “accessType” in Access API has following enum A, B and C. Changing these enum to more meaningful name like “FullAccess”, “TemporaryAccess” and “NotAccess” is considered as breaking changes.

4.2 Changing the value of the field

It is considered as a breaking change if the format for currency change from “Norwegian kroner” to the ISO standard 4217 (“NOK”). This requires a new major version.

Example:
Version 1.3.4:

"orders": {
      "orderId": 9,
      "orderTime": 1559372400000,
      "orderAmount": 295,
      "currency": "Norwegian kroner"
      "customerNumber": 563457
    }

Version 2.0.0:

"orders": {
      "orderId": 9,
      "orderTime": 1559372400000,
      "orderAmount": 295,
      "currency": "NOK"
      "customerNumber": 563457
    }

It is not required to have major version if we keep both fields as it is backwards compatible.