Submit the cool project: your API client from one configuration file

Hi, Habrahabr! I recently made a tool that generates a whole client wrapper over any API that you only want from a single yml file, and then immediately loads it into the Python Package Index (PyPi). Yes, you can install the result into your any project using pip and start using it. More details under the cut!

Example

Take a look at the fictional http request code for the Game of Thrones API server that you would write using the requests library.

import requests 
create_jon_snow_user = requests.post(
    'https://gameofthrones.com/api/v1/user', 
    params={
        'id': 7,
        'name': 'Jon',
        'surname': 'Snow',
    }
)
get_jon_snow_user = requests.get(
    'https://gameofthrones.com/api/v1/user', params={'id': 7}
)
create_jon_snow_castle = requests.post(
    'https://gameofthrones.com/api/v1/user/castle', 
    params={
        'id': 7,
        'castle': 'Winterfell',
    }
)

And now for the code that makes it possible to use syntactic, comfortable for the client (developer) constructions.

from gameofthrones_api import gameofthrones_api_client as got_api_client
create_jon_snow_user = got_api_alient.user.create({
    'id': 7,
    'name': 'Jon',
    'surname': 'Snow'
})
get_jon_snow_user = got_api_alient.user.get({'id': 7})
create_jon_snow_castle = got_api_alient.user.castle.create({
    'id': 7,
    'castle': 'Winterfell',
})

How it works

The acg tool ( link to Github ) opens this possibility , but for this it needs a file with the name .acg.yml in the following form:

pypi:
  username: dmytrostriletskyi
  password: d843rnd3
acg:
  name: gameofthronesapi
  version: 0.1.5
  api: https://gameofthrones.com/api/v1
  services:
    user:
      url: /user
      endpoints: create:post, get:get
    user.castle:
      url: /user/castle
      endpoints: create:post

You specify your PyPi username and password so that acg downloads the client to your account and this package can be installed via pip - acg writes the parameters to the .pypirc file , which is needed to download your package in the Python Package Index (PyPi).

Now to the back-end server to which you are writing the client:

• in .acg.yml the api field is available , where you need to specify the root (address), from which there are already branches to various requests. For example, the root is your myapi.com API , and the branch is / users / all .
• in services has for every taste, you can specify any number of "ways", they all end endpointami (endpoints) and are available in the address to which they "belong".
• endpoints in acg in configurations is the name of the method and its type of HTTP request. An example from the configurations above: user.castle.create , post-request, to the address / user / castle . Having an endpoint is useful when a single path supports many request types (get, post, delete for a single address). For example, apple.iphone.ten.account can support endpoints get (request type get), delete (delete), create (post), modify (put) to the address / apple / iphone / ten / account.
• Many endpoints to the same address are written on a single line to the endpoints item , separated by commas - get: get, delete: delete, create: post, modify: put (example).

Install acg

You can install acg using pip.

$ pip install acg

Pip3:

$ pip3 install acg

Or compile the source code:

$ python setup.py install

Acg team

We created .acg.yml , entered our settings there, opened the terminal in the configuration directory:

$ acg

You also continue to work with acg if you want to update the configurations and client accordingly. Remember that for each new download you need to change the version of your client package. Remember to use the --no-cache-dir or -U flag when installing a new version of your package.

To avoid conflicts, I advise you to delete all generated projects (folders) of your project (each time acg builds the project again).

How to install and use your client

Installation will require the familiar `pip install {name}` command, where the package name will be the value name in the configuration file.

It is also simple to use, import an object with all the necessary parameters from your installed module. The client always repeats the name of the package, but complements itself with the _client part .

For example, you wrote configurations for the telegrambotapi project .
Then use the client in Python code like this:

from telegrambotapi import telegrambotapi_client