client.md

Clients

In order to interact with an API using Core API, a client instance is required.

The client is used to fetch the initial API description, and to then perform interactions against the API.

An example client session might look something like this:

from coreapi import Client

client = Client()
document = client.get('https://api.example.org/')
data = client.action(document, ['flights', 'search'], params={
    'from': 'LHR',
    'to': 'PA',
    'date': '2016-10-12'
})

---

Instantiating a client

The default client may be obtained by instantiating an object, without passing any parameters.

client = Client()

A client instance holds the configuration about which transports are available for making network requests, and which codecs are available for decoding the content of network responses.

The signature of the Client class is:

Client(decoders=None, transports=None, auth=None, session=None)

Arguments:

• decoders - A list of decoder instances for decoding the content of responses.
• transports - A list of transport instances available for making network requests.
• auth - A authentication instance. Used when instantiating the default HTTP transport.
• session - A requests session instance. Used when instantiating the default HTTP transport.

For example the following would instantiate a client, authenticated using HTTP basic auth, that is capable of decoding either Core JSON schema responses, or decoding plain JSON data responses:

from coreapi import codecs
from coreapi.auth import BasicAuthentication

decoders = [
    codecs.CoreJSONCodec(),
    codecs.JSONCodec()
]
auth = BasicAuthentication(domain='*', username='example', password='xxx')
client = Client(decoders=decoders, auth=auth)

When no arguments are passed, the following defaults are used:

decoders = [
    codecs.CoreJSONCodec(),     # application/vnd.coreapi+json
    codecs.JSONCodec(),         # application/json
    codecs.TextCodec(),         # text/*
    codecs.DownloadCodec()      # */*
]

transports = [
    transports.HTTPTransport(auth=auth, session=session)  # http, https
]

The configured decoders and transports are made available as read-only properties on a client instance:

• .decoders
• .transports

---

Making an initial request

Signature: get(url)

Make a network request to the given URL. If fetching an API schema or hypermedia resource, then this should typically return a decoded Document.

• url - The URL that should be retrieved.
• format - Optional. Force the given codec to be used when decoding the response.

For example:

document = client.get('https://api.example.org/')

---

Interacting with an API

Signature: action(self, document, keys, params=None)

Effect an interaction against the given document.

• document - A Document instance.
• keys - A list of strings that index a Link within the document.
• params - A dictionary of parameters to use for the API interaction.

For example, making a request without any parameters:

data = client.action(document, ['flights', 'list_airports'])

Or making a request, with parameters included:

data = client.action(document, ['flights', 'search'], params={
    'from': 'LHR',
    'to': 'PA',
    'date': '2016-10-12'
})