genericclient 1.4.2

Instantiation

myclient = GenericClient(url, auth=None, session=None, adapter=None, trailing_slash=False, autopaginate=None)

Arguments:

• url: The root URL of your API

• auth: The auth for your API. You can pass anything that requests can accept as auth.

• session: Pass a session instance to have requests use that session. If None (the default), it will instantiate an instance of requests.session for you.

• adapter: optional session adapter for requests.

• trailing_slash: You can set this to True if your API’s URLs end with a /

• autopaginate: You can set this to a callable to fetch all pages resulting from a request. Currently, the only callable included is genericclient.pagination.link_header, which supports [RFC5988](https://tools.ietf.org/html/rfc5988).

Endpoints

Endpoints are available as properties and items on the main instance:

myclient.posts.all()  # GET /posts/
myclient["active-users"].all()  # GET /active-users/

myclient.posts.all()  # GET /posts/

myclient.posts.filter(blog=12, status=1)  # GET /posts/?blog=12&status=1

myclient.posts.filter(blog=12, status=1)  # GET /posts/?blog=12&status=1
myclient.posts.filter(id=12)  # GET /posts/12/
myclient.posts.filter(slug='12-ways-clickbait')  # GET /posts/12-ways-clickbait/

post = myclient.posts.create({'blog': 12, 'status': 1})  # POST /posts/

# Assuming it doesn't exist
post = myclient.posts.get_or_update(slug='my-post', defaults={'status': 1})  # GET /posts/my-post/, then POST /posts/

post = myclient.posts.create_or_update({'status': 1})  # POST /posts/
post = myclient.posts.create_or_update({'id': 1234, 'status': 1})  # PUT /posts/1234/

post = myclient.posts.create_or_update({'id': 1234})  # PUT /posts/1234/
# <- server returns 400
# -> PATCH /posts/1234/

myclient.posts.delete(24)  # DELETE /posts/24/

Resources

All endpoints methods (with the exception of .delete()) return either a Resource or a list of Resource s.

A Resource is just a wrapping class for a dict, where keys can be accessed as properties.

Additionally, Resource s have a special property called .payload, which contains the original payload received from the server.

Resource s have the following methods:

Resource.delete() will result in a DELETE, with Resource.id as par of the URL:

blog = myclient.posts.create({'blog': 12, 'status': 1})  # POST /posts/
blog.delete()  # DELETE /blog/345/ -- the ID 345 was returned by the server in the previous response

Resource.save() will result in a PUT, with Resource.id as par of the URL. If the server returns a 400 error, a PATCH request will be re-issued:

post = myclient.posts.create({'blog': 12, 'status': 1})  # POST /posts/
post.status = 2
post.save()  # PUT /posts/345/

post = Resource(id=345, status=1)
post.save()  # PUT /posts/345/
# <- server returns 400
# -> PATCH /posts/345/

ResourceSets

Whenever a method returns a list of Resources, they list will be wrapped in a ResultSet.

A ResultSet is a just a list object, with the addition of a .response containing the original response from the server.

Customizing Endpoints and Resources

Resources can be customized by subclassing genericclient.Resource.

The most common reason is specifying the name of the primary key:

from genericclient import Resource


class PostResource(Resource):
    pk_name = 'slug'

Endpoints can be customized by subclassing genericclient.Endpoint:

form genericclient import Endpoint


class PostEndpoint(Endpoint):
    resource_class = PostResource

You can then subclass genericclient.GenericClient to tell the client which endpoint classes to use on each endpoint:

from genericclient import GenericClient

class Client(GenericClient):
    endpoint_classes = {
        'posts': PostEndpoint,
    }

Routes

If your API has some non-RESTful calls within the main endpoints (sometimes referred as detail_route and list_route), you can use genericclient to call them:

myclient.posts(id=123).publish(date=tomorrow)

myclient.blogs().ping()

Routes http calls use POST by default, but you can specify something else by using the _method argument:

myclient.posts(_method='get', id=123).pingbacks()

myclient.blogs(_method='get').visits()

Note that this calls will return an instance of genericclient.ParsedResponse, instead of instances of genericclient.Resource,