API connector

New API = New Module

When adding a new API connector, please create a new module within dabeplech with the api name. (e.g. dabeplech/myawesomeapi.py).

Note

To ease import while using dabeplech, do not forget to import your new classes to dabeplech/__init__.py.

Creating your API connector

Base Structure

All API connectors try to follow the same structure and therefore has to inherit from dabeplech.base.BaseAPI.

Here is the structure of the class:

class dabeplech.base.BaseAPI[source]

Bases: object

Base class to build your API connector.

BASE_URL = ''
HEADERS = {'Accept': '*/*', 'Content-type': 'application/json'}
ROUTE = ''
SESSION

alias of requests.sessions.Session

When adding a new API connector, you inherit from the BaseAPI class and then overload BASE_URL with the base url of your API. From this new class you can create as many child classes as routes the API provides and overload ROUTE class attribute.

Then, you need to add methods to perform requests (GET, POST…) and the approach will depend on the API your are adding:

Example

Let’s say we want to add our new awesome API which has https://awesomebioinfo.com/ as base url and contains two routes:

  • https://awesomebioinfo.com/genes: obtain information about genes

  • https://awesomebioinfo.com/organisms: obtain information about organisms

Here is the code that we write to add this API in dabeplech/awesomebioinfo.py file:

from dabeplech.base import BaseAPI

class AwesomebioinfoAPI(BaseAPI):
    BASE_URL = "https://awesomebioinfo.com/"

class AwesomebioinfoGenesAPI(AwesomebioinfoAPI):
    ROUTE = "genes/"

class AwesomebioinfoOrganismsAPI(AwesomebioinfoAPI):
    ROUTE = "organisms/"

Warning

As it is, your connectors won’t work since no methods are defined to perform requests. This question is adressed below.

Once this module has been created, add it to the dabeplech/__init__.py file so that it can be imported. In this case, the code added at the bottom of this file would be:

from .awesomebioinfo import ( #noqa
    AwesomebioinfoAPI,
    AwesomebioinfoGenesAPI,
    AwesomebioinfoOrganismsAPI,
)

Adding an API returning JSON

A list of Mixins is available to build your API connectors. You just need to perform multiple inheritance for your new classes with the corresponding Mixins to add the methods. Here is a description of the different Mixins:

class dabeplech.base.LISTMixin[source]

Bases: object

Corresponds to a GET that retrieve list of items.

list(params=None)[source]

Perform GET request to the service.

Parameters

params – query params for the request

Return type

list

class dabeplech.base.GETMixin[source]

Bases: object

Corresponds to a GET that retrieve one item from its ID.

get(entry_id, params=None)[source]

Perform GET request to the service.

Parameters

  • entry_id – ID of the entry you want to retrieve

  • params – query params for the request

Return type

dict

class dabeplech.base.POSTMixin[source]

Bases: object

Corresponds to a POST operation.

post(data)[source]

Perform POST request to the service.

Args

data: data to send in the body of your POST

Return type

dict

class dabeplech.base.PUTMixin[source]

Bases: object

Corresponds to a PUT operation.

put(data, entry_id=None)[source]

Perform PUT request to the service.

Parameters

  • data – data to send in the body of your PUT

  • entry_id – ID of the entry you want to update

Return type

Union[dict, list]

Example

From the previous example, we consider the two endpoints allow to obtain list of genes and organisms, but also retrieve an item based on its ID. The code becomes:

from dabeplech.base import BaseAPI, LISTMixin, GETMixin

class AwesomebioinfoAPI(BaseAPI, LISTMixin, GETMixin):
    BASE_URL = "https://awesomebioinfo.com/"

class AwesomebioinfoGenesAPI(AwesomebioinfoAPI):
    ROUTE = "genes/"

class AwesomebioinfoOrganismsAPI(AwesomebioinfoAPI):
    ROUTE = "organisms/"

Now you can use your api connector (considering classes are added to dabeplech/__init__.py):

from dabeplech import AwesomebioinfoGenesAPI

api = AwesomebioinfoGenesAPI()

# Get all genes
all_genes = api.get_all()
# Get one gene with its ID
the_gene = api.get('my-fav-gene')

Adding an API based on a Parser

There is not automatic way to help you use your parsers while adding an API connector using a parser to structure the response into JSON.

At the moment, please refer to the dabeplech.kegg module for examples using parsers.

Note

A more abstracted way of dealing with parser will be extracted in the future when needed. The Kegg case being particular, it needs its own methods.

Adding an API based on a Scrapper

There is not automatic way to help you use your scappers while adding an API connector using a scrapper to structure the response into JSON.

At the moment, please refer to the dabeplech.ncbi_taxonomy module for examples using scrappers.