Deprecating API Endpoints

Deprecating API endpoints without clear warnings can lead to broken integrations. APIMatic makes the deprecation process very simple by notifying developers when they use deprecated methods and educate them on the recommended alternatives.

Key Benefits

Deprecation Warnings: Deprecated endpoints trigger compiler warnings or runtime notices.
Detailed Deprecation Info: SDKs display the deprecation reason, affected version, and suggested alternatives.
Backward Compatibility: Deprecated endpoints remain functional to avoid breaking existing implementations while encouraging updates.

Mark endpoints deprecated in your OpenAPI Definition

The x-deprecation-details OpenAPI extension allows API authors to provide deprecation details such as the reason, the version in which a method was deprecated, and alternative options.

Below is an example demonstrating how to mark an endpoint as deprecated using this extension:

openapi: 3.0.3
info:
  title: Product Management API
  description: API for managing products in an inventory system.
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /products/legacy:
    get:
      summary: Retrieve all products (Deprecated)
      description: |
        **This endpoint is deprecated.**  
        Use the `/products` endpoint for enhanced filtering and pagination capabilities.
      operationId: getAllProductsLegacy
      deprecated: true
      responses:
        '200':
          description: A list of products.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'
        '410':
          description: This endpoint is no longer available.
components:
  schemas:
    Product:
      type: object
      properties:
        productName:
          type: string
          description: The name of the product.
        quantity:
          type: integer
          description: Quantity of the product in stock.
      required:
        - productName

Usage in SDKs

Once the OpenAPI definition is updated, SDKs for supported languages will incorporate the deprecation details.

/**
 * **This endpoint is deprecated.**
 * Use the `/products` endpoint for enhanced filtering and pagination capabilities.
 *
 *
 * @return Response from the API call
 * @deprecated
 */
async getAllProductsLegacy(
  requestOptions?: RequestOptions
): Promise<ApiResponse<Product[]>> {
  ...
}

/**
 * **This endpoint is deprecated.** Use the `/products` endpoint for enhanced filtering and
 * pagination capabilities.
 * @deprecated
 * 
 * @return    Returns the List of Product response from the API call
 * @throws    ApiException    Represents error response from the server.
 * @throws    IOException    Signals that an I/O exception of some sort has occurred.
 */
@Deprecated
public List<Product> getAllProductsLegacy() throws ApiException, IOException {
  ...
}

@deprecated()
def get_all_products_legacy(self):
    """Does a GET request to /products/legacy.

    **This endpoint is deprecated.**  
    Use the `/products` endpoint for enhanced filtering and pagination
    capabilities.

    Returns:
        List[Product]: Response from the API. A list of products.

    Raises:
        APIException: When an error occurs while fetching the data from
            the remote API. This exception includes the HTTP Response
            code, an error message, and the HTTP body that was received in
            the request.

    """

/**
 * **This endpoint is deprecated.**
 * Use the `/products` endpoint for enhanced filtering and pagination capabilities.
 *
 *
 * @deprecated
 *
 * @return Product[] Response from the API call
 *
 * @throws ApiException Thrown if API call fails
 */
public function getAllProductsLegacy(): array
{
  ...
}

/// <summary>
/// **This endpoint is deprecated.**  .
/// Use the `/products` endpoint for enhanced filtering and pagination capabilities.
/// </summary>
/// <param name="cancellationToken"> cancellationToken. </param>
/// <returns>Returns the List of Models.Product response from the API call.</returns>
[Obsolete]
public async Task<List<Models.Product>> GetAllProductsLegacyAsync(CancellationToken cancellationToken = default)
{
  ...
}

# **This endpoint is deprecated.**
# Use the `/products` endpoint for enhanced filtering and pagination
# capabilities.
# @return [Array[Product]] response from the API call.
def get_all_products_legacy
  ...
end

// GetAllProductsLegacy takes context as parameters and
// returns an models.ApiResponse with []models.Product data and
// an error if there was an issue with the request or response.
// Deprecated: getAllProductsLegacy is deprecated
// **This endpoint is deprecated.**  
// Use the `/products` endpoint for enhanced filtering and pagination capabilities.
func (a *APIController) GetAllProductsLegacy(ctx context.Context) (
    models.ApiResponse[[]models.Product],
    error) {
    ...
}

Compiler or Runtime Warnings for Deprecated Endpoints

Here are examples of compiler or runtime warnings generated for the example in the respective languages. These warnings or messages typically appear during the build process or when the deprecated methods are invoked.

// TypeScript generates a warning when using deprecated methods like this:
let products = await api.getAllProductsLegacy();
// Warning: 'getAllProductsLegacy' is deprecated.
// Use the `/products` endpoint for enhanced filtering and pagination capabilities.

// Java produces a compiler warning if you call a deprecated method,
// unless the warning is suppressed with `@SuppressWarnings("deprecation")`.
List<Product> products = api.getAllProductsLegacy(); 
// Warning: getAllProductsLegacy() in APIController has been deprecated.

# The `deprecated` library (commonly used for marking methods as deprecated in Python)
# produces a runtime warning when the method is called:
api.get_all_products_legacy()
# WARNING: Call to deprecated method (or function) get_all_products_legacy.
# **This endpoint is deprecated.** Use the `/products` endpoint for enhanced filtering and pagination capabilities.

// PHP typically logs a warning if the `@deprecated` tag is documented
// and a custom static analysis tool or IDE detects it.
// A runtime error like this can appear based on tool configuration:
$products = $api->getAllProductsLegacy(); 
// Warning: Call to deprecated function: getAllProductsLegacy()

// .NET marks the method with `[Obsolete]` which shows a warning during compile time:
var products = await api.GetAllProductsLegacyAsync();
// Warning: 'APIController.GetAllProductsLegacyAsync(CancellationToken)' is obsolete: 'This endpoint is deprecated. Use the `/products` endpoint for enhanced filtering and pagination capabilities.'

# Ruby produces runtime warnings if the `warn` or similar deprecation notices are manually triggered in the method:
api.get_all_products_legacy
# WARNING: This endpoint is deprecated. Use the `/products` endpoint for enhanced filtering and pagination capabilities.

// Go does not have built-in support for deprecation warnings, but static analysis tools like `golint`
// can generate warnings based on the comment `// Deprecated:`:
api.GetAllProductsLegacy(ctx)
// Warning from linting tool:
// GetAllProductsLegacy is deprecated: Use the `/products` endpoint for enhanced filtering and pagination capabilities.

These warnings rely on language-specific tools or built-in annotation mechanisms to indicate deprecation during development or runtime.

Key Benefits​

Mark endpoints deprecated in your OpenAPI Definition​

Usage in SDKs​

Compiler or Runtime Warnings for Deprecated Endpoints​

Key Benefits

Mark endpoints deprecated in your OpenAPI Definition

Usage in SDKs

Compiler or Runtime Warnings for Deprecated Endpoints