Submit the cool project: свой API-client с одного конфигурационного файла


    Привет, Хабрахабр! Я тут недавно сделал тулзу, которая генерирует целую обертку-клиент над любым API, который ты только захочешь, с одного yml-файла, а потом сразу же загружает его в Python Package Index (PyPi). Да, результат можно установить в свой любой проект с помощью pip и начать пользоваться. Подробнее под катом!

    Пример


    Посмотрите на код вымышленных http-запросов на Game of Thrones API-сервер, который бы вы написали с помощью библиотеки requests.

    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',
        }
    )
    

    А теперь на код, который делает возможным использовать синтаксические, комфортные для клиента (девелопера), конструкции.

    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',
    })
    

    Как это работает


    Такую возможность открывает инструмент acg (ссылка на Github), но для этого ему необходим файл с названием .acg.yml в следующем виде:

    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
    

    Вы указываете свои PyPi логин и пароль, чтобы acg загрузил клиент на ваш аккаунт и этот пакет мог быть доступен для установки через pipacg вписывает параметры в файл .pypirc, который нужен для загрузки вашего пакета в Python Package Index (PyPi).

    Теперь к back-end серверу, к которому вы пишите клиент:

    • в .acg.yml доступно поле api, где нужно указать корень (адрес), от которого уже идут ответвления на различные запросы. Например, корнем является ваша API myapi.com, а ответвлением /users/all.
    • в services уже на любой вкус можно указать сколько угодно «путей», все они заканчиваются эндпоинтами (endpoints) и имеют в наличие адрес, к которому они «принадлежат».
    • endpoints в пункте acg в конфигурациях — это название метода и его тип запроса HTTP. Пример из конфигураций выше: user.castle.create, post-запрос, на адрес /user/castle. Наличие endpoint полезно, когда один путь поддерживает много типов запроса (get, post, delete для одного адреса). Например, apple.iphone.ten.account может поддерживать endpoints get (тип запроса get), delete (delete), create (post), modify (put) к адресу /apple/iphone/ten/account.
    • Множество эндпоинтов к одному адресу записываются в одну строку к пункту endpoints через запятую — get:get, delete:delete, create:post, modify:put (пример).

    Установка acg


    Установить acg можно с помощью pip.

    $ pip install acg
    

    Pip3:

    $ pip3 install acg
    

    Или собрать исходный код:

    $ python setup.py install
    

    Команда acg


    Создали .acg.yml, вписали туда свои настройки, открыли терминал в директории с конфигурациями:

    $ acg
    

    Вы также продолжаете работать с acg, если хотите обновить конфигурации и клиент соответственно. Помните, что на каждую новую загрузку необходимо менять версию вашего клиента-пакета. Не забывайте использовать флаг --no-cache-dir или -U при установке новой версии своего пакета.

    Чтобы не было конфликтов, советую удалять все сгенерированные проекты (папки) вашего проекта (каждый раз acg строит проект заново).

    Как установить и использовать свой клиент


    Установка потребует знакомой вам команды `pip install {name}`, где названием пакета будет значение name в конфигурационном файле.

    Использовать также просто, импортируете объект со всеми нужными параметрами из своего установленного модуля. Клиент всегда повторяет название пакета, но дополняет себя частью _client.

    Например, вы написали конфигурации под проект telegrambotapi.
    Тогда используйте клиент в Python-коде так:

    from telegrambotapi import telegrambotapi_client
    
    Поделиться публикацией

    Комментарии 4

      0
      Мне кажется, или «скрипач не нужен»?
        0
        Yet another Swagger?
          0
          А как быть с авторизацией?
            0

            Это все хорошо, когда у Вас пет-проджект и ваша логика укладывается в CRUD. На больших проектах это работать не будет (почти всегда бизнес логика выходит за пределы CRUD). Более того, давно существует немало инструментов, которые умеют генерировать rest-api из RAML.

            Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

            Самое читаемое