# API life cycle and deprecation strategy

To keep you up to date with the latest versions of APIs, Pismo must occasionally deprecate and decommission older versions of APIs. When an endpoint or API is deprecated, Pismo strongly recommends updating to the newest versions before the decommission date. This allows for a smooth upgrade path to a newer release.

> 📘 Deprecation and removal schedule
>
> For a current list of deprecated endpoints, see the [API endpoint deprecation and removal schedule](https://developers.pismo.io/pismo-docs/docs/deprecation-schedule).

# Terms and concepts

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Term
      </th>

      <th>
        Definition
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        API and endpoint
      </td>

      <td>
        Each product on the Pismo platform has a specific API, providing many services, known as endpoints. A Pismo API provides at least one endpoint. Endpoints represent the services that can be executed by an API product.

        Every endpoint belongs to a specific API. For example:

        <ul>
          <li>Products: Accounts API, Cards API</li>
          <li>Endpoints: Get account status, Create a card</li>
        </ul>

        <br />
      </td>
    </tr>

    <tr>
      <td>
        Deprecation
      </td>

      <td>
        A service has been ended (with or without a replacement becoming available). Support for this service is limited to bug fixes only.
      </td>
    </tr>

    <tr>
      <td>
        Sunsetting
      </td>

      <td>
        Period of time from the deprecation date to decommissioning. The sunsetting period is usually six months. However, endpoints presenting vulnerability issues are decommissioned within three months.
      </td>
    </tr>

    <tr>
      <td>
        Decommissioning
      </td>

      <td>
        Older version is no longer available. Requests sent to this version fail beginning on the decommissioning date.
      </td>
    </tr>
  </tbody>
</Table>

# API life cycle

<Table align={["left","left","left","left","left"]}>
  <thead>
    <tr>
      <th>
        Version Status
      </th>

      <th>
        Description
      </th>

      <th>
        Documentation
      </th>

      <th>
        Support
      </th>

      <th>
        Pismo Bulletin
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Active
      </td>

      <td>
        Most up-to-date and recommended API version
      </td>

      <td>
        Available on launch date.
      </td>

      <td>
        Fully supported. Update with bug fixes and new features.
      </td>

      <td>
        Notifications published two weeks prior to launch and again on launch date.
      </td>
    </tr>

    <tr>
      <td>
        Deprecated
      </td>

      <td>
        API is scheduled for decommissioning and may or may not be superseded by a newer version.

        New customers or new integrations by existing customers are denied access to deprecated APIs.
      </td>

      <td>
        The version is marked as *Deprecated* on the day of deprecation.
      </td>

      <td>
        Supported for six months from the deprecation date (bug fixes only).
      </td>

      <td>
        Notification published on deprecation date.
      </td>
    </tr>

    <tr>
      <td>
        Decommissioned
      </td>

      <td>
        API is no longer available. The version is decommissioned six months after in the deprecated status.
      </td>

      <td>
        No documentation provided.
      </td>

      <td>
        No support provided.
      </td>

      <td>
        Notifications published 90, 60, 30, 15, and 7 days prior to decommissioning and again on the decommissioning date.
      </td>
    </tr>
  </tbody>
</Table>

# Communication schedule

| Schedule                                          | Communication method                                |
| :------------------------------------------------ | :-------------------------------------------------- |
| Deprecation date                                  | Pismo Bulletin and [Changelog](https://developers.pismo.io/pismo-docs/docs/pismo-changelog) |
| 90, 60, 30, 15, and 7 days before decommissioning | Pismo Bulletin                                      |
| Decommission date                                 | Pismo Bulletin and [Changelog](https://developers.pismo.io/pismo-docs/docs/pismo-changelog) |

# API upgrades

The URL for an endpoint includes an element specifying the version of the API it uses. For example, in the URL `https://api-sandbox.pismolabs.io/events/v1/timeline`, the **v1** element indicates that it uses version 1 of the API for that endpoint. For more information about endpoint structure, see [Environments](https://developers.pismo.io/pismo-docs/docs/environments).

Your API version controls what parameters you can send in requests and which ones you receive in the responses. So, if you’re using an older version of an API, you should upgrade to the latest version to take advantage of new functionality or improved processing. To see if there are any new API versions available, check out the Pismo Changelog and the latest version of the documentation.

> 📘 Outdated API versions
>
> In exceptional cases, Pismo may maintain an outdated API alongside a current one. In these cases, you should use the **latest version** for all new development. This helps to avoid rework when the outdated API eventually is deprecated.

# Backward-compatible changes

Backward compatible changes in your version are available automatically. These changes typically introduce new features or improve performance, but do not disrupt your current implementation. To use a newer version, you shouldn't have to do anything to keep things working correctly.

The following changes are backward compatible.

* Adding API resources
* Adding optional request parameters to existing API methods
* Adding properties to existing API responses