Client Library

API Star includes a dynamic client library.

Typically developers have had to build client libraries for each new API service, or auto-generate a new client on each new release.

The API Star dynamic client library works differently, in that it simply takes the API schema as an argument when the client is instantiated, and then allows you to interact with the API.

import apistar

schema = """
openapi: 3.0.0
  title: Widget API
  version: '1.0'
  description: An example API for widgets
      summary: List all the widgets.
      operationId: listWidgets
      - in: query
        name: search
        description: Filter widgets by this search term.
          type: string

client = apistar.Client(schema)
result = client.request('listWidgets', search='cogwheel')

Instantiating a client

You can instantiate an API client like so:

import apistar

client = apistar.Client(schema=...)

Signature: Client(schema, format=None, encoding=None, auth=None, decoders=None, encoders=None, headers=None, session=None, allow_cookies=True)

Making requests

Requests to the API are made using the request method, including the operation id and any parameters.

result = client.request('listWidgets', search='cogwheel')

The result will be a data structure, decoded appropriately from the response content, as determined by the Content-Type header of the response.

In the event of an error response (4xx or 5xx status codes) the client will raise apistar.exceptions.ErrorResponse.

There are three attributes on here that you may wish to inspect:

If the request is made with an incorrect set of parameters, or if the client cannot fulfil the request for some reason then apistar.exceptions.ClientError will be raised.


You can use any standard requests authentication class with the API client.

import apistar
from requests.auth import HTTPDigestAuth

schema = {...}

auth = HTTPDigestAuth('user', 'pass')
client = apistar.Client(schema=schema, auth=auth)

API Star also includes some authentication classes that you can use for making API requests.

Decoding responses

The return result is determined from the response by selecting a decoder based on the response content-type header, and allowing it to decode the response content.

By default the client has the following decoders enabled:

You can customize which decoders are installed on a client like so:

client = apistar.Client(schema, decoders=[JSONDecoder()])

In the example above the client would send application/json in the Accept header, and would raise an error on any other content being returned.

Writing a custom decoder

To write a custom decoder you should subclass apistar.client.decoders.BaseDecoder, and override the media_type attribute, and the decode(self, response) method.

For example:

from apistar.client.decoders import BaseDecoder
import csv

class CSVDecoder(BaseDecoder):
    media_type = 'text/csv'

    def decode(self, response):
        lines = response.text.splitlines()
        reader = csv.reader(lines, delimiter=',')
        return [row for row in reader]

Encoding requests

The request body is determined depending on the encoding used for the request.

By default the client has the following encoders enabled:

You can customize which decoders are installed on a client like so:

client = apistar.Client(schema, encoders=[JSONEncoder()])

In the example above the client would send application/json in outgoing requests, and would raise an error for requests which required any other encoding to be used.

Writing a custom encoder

Typically the default set of encoders will be appropriate for handling the encoding of the request body, since JSON or either of the types of form data are by far the most commonly used encodings for HTTP requests. However you can customize this behaviour if needed, in order to support endpoints which expect some other type of encoding.

To write a custom encoded you should subclass apistar.client.encoders.BaseEncoder, and override the media_type attribute, and the encode(self, options, content) method.

The encode method is used to modify the options that are passed to requests.send(...) when making the outgoing request.

For example:

from apistar.client.encoders import BaseEncoder

class TextEncoder(BaseDecoder):
    media_type = 'text/plain'

    def encode(self, options, content):
        assert isinstance(content, str), 'The request body for this endpoint must be a string.'
        options['headers']['content-type'] = 'text/plain'
        options['data'] = content