Core API Python Client

2.3.3 · deprecated · verified Sat Apr 11

The `coreapi` library is a Python client for interacting with web APIs that expose Core API schemas or hypermedia formats. It supports formats like CoreJSON, OpenAPI (for schema description), JSON Hyper-Schema, and HAL. The latest stable version, 2.3.3, was released in October 2017. This library is largely considered superseded, particularly within the Django REST Framework ecosystem where its schema generation was deprecated in favor of OpenAPI.

Warnings

breaking Django REST Framework (DRF) officially deprecated CoreAPI-based schema generation in version 3.10, transitioning to OpenAPI. DRF 3.12 was planned to remove CoreAPI support entirely, meaning existing DRF applications relying on `rest_framework.schemas.coreapi` will break or require migration.
Fix: Migrate DRF schema generation to OpenAPI-based solutions. For client interaction with Core API services, continue using `coreapi` library directly, but be aware of its maintenance status.
deprecated The `core-api/python-client` GitHub repository is marked as 'Public archive', indicating that the project is no longer actively maintained. The last PyPI release was in October 2017. Users should be aware of potential lack of updates, bug fixes, or security patches.
Fix: Consider alternatives like `requests` with a schema validation library or clients generated from OpenAPI specifications for new projects. For existing projects, proceed with caution and be prepared to fork or maintain the library internally.
gotcha Users have reported compatibility problems with `coreapi` on Python 3.10 and newer versions, often stemming from indirect dependencies like `markupsafe` or `jinja2`. This can lead to import errors or runtime exceptions.
Fix: Explicitly pin versions of transitive dependencies like `jinja2` and `markupsafe` to older, compatible versions (e.g., `jinja2<3.1`, `markupsafe<2.1`), if these are indeed the root cause. A full resolution might require using an older Python version or avoiding `coreapi`.
gotcha Common runtime errors include `coreapi.exceptions.LinkLookupError` if the specified keys do not map to an existing link in the API document, and `coreapi.exceptions.ParameterError` if action parameters are missing, invalid, or do not match the API's requirements.
Fix: Always inspect the API document retrieved by `client.get()` to understand the available actions and their required/optional parameters. Implement robust error handling (e.g., `try...except coreapi.exceptions.LinkLookupError`) for API interactions.

Install

pip install coreapi Install stable version

Imports

Client
```
from coreapi import Client
```
While `rest_framework.schemas.coreapi.AutoSchema` existed for Django REST Framework, it is deprecated in favor of OpenAPI. The coreapi.Client is for direct client interaction, not schema generation within DRF.

Quickstart

This quickstart demonstrates how to initialize a `coreapi.Client`, fetch an API document (schema), and perform an action (like listing resources) based on the document's structure. It uses `http://notes.coreapi.org/` as an example API endpoint.

import coreapi
import os

# The Core API library interacts with APIs based on their exposed schema/hypermedia.
# We'll use a public example service from coreapi.org for demonstration.
# Replace 'http://notes.coreapi.org/' with your actual Core API endpoint.
API_URL = os.environ.get('COREAPI_EXAMPLE_URL', 'http://notes.coreapi.org/')

try:
    # 1. Create a client instance
    client = coreapi.Client()

    # 2. Retrieve the API document (schema/hypermedia description)
    document = client.get(API_URL)
    print(f"Successfully retrieved API document for: {document.title}")

    # 3. Interact with the API using actions defined in the document
    # This example assumes the 'notes' service at API_URL has a 'list' action.
    # Adjust 'keys' and 'params' based on the specific API you are interacting with.
    if 'notes' in document and 'list' in document['notes']:
        print("\nAttempting to list notes...")
        notes_list = client.action(document, ['notes', 'list'])
        print(f"Retrieved {len(notes_list)} notes.")
        for note in notes_list:
            print(f"- {note.get('description', 'No description')}")
    else:
        print(f"'notes' or 'list' action not found in document from {API_URL}. Cannot demonstrate interaction.")

except coreapi.exceptions.NetworkError as e:
    print(f"Error: Network issue connecting to {API_URL}. Details: {e}")
    print("Please ensure the API endpoint is correct and accessible.")
except coreapi.exceptions.ErrorMessage as e:
    print(f"Error: API returned an error message. Status: {e.status_code}, Detail: {e.error}")
except coreapi.exceptions.LinkLookupError as e:
    print(f"Error: Invalid action path. Details: {e}")
    print("Check the keys passed to client.action() match the API document structure.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

view raw JSON →