В этой статье я рассмотрю практику использования библиотек разработчиками на разных языках программирования для упрощения интеграции с API.

Очевидно, скорость и эффективность — ключевые факторы успеха для крупных компаний, желающих продвигать свои услуги на рынке. Один из важных аспектов этого процесса — интеграция с различными API (Application Programming Interface), которые позволяют взаимодействовать с внешними сервисами и получать доступ к их функциональности.

В частности, я создал библиотеку asynclientmts на языке Python, которая предоставляет асинхронный клиент для работы с API МТС Exolve — платформой для взаимодействия с коммуникационными услугами.

Создаваемая библиотека будет содержать класс AsyncClientMTS.

Он включает в себя методы для взаимодействия с API и позволяет разработчикам быстро интегрировать его в свои проекты. Это значительно сокращает время разработки и запуска продукта, освобождает разработчиков от необходимости писать собственный асинхронный клиент.

Практика разработки собственных готовых библиотек для различных языков программирования имеет ряд преимуществ для крупных компаний, стремящихся продвигать свои услуги. Использование готовых библиотек значительно ускоряет процесс разработки и позволяет быстрее запустить продукт на рынке.

Кроме того, раз библиотеки могут построить на разных языках программирования, это делает их универсальными и применимыми для различных проектов. Независимо от того, используется ли Python, JavaScript, Ruby или другой язык программирования, разработчики могут сразу найти подходящую библиотеку для интеграции с нужным API. Это упрощает межплатформенную разработку и позволяет компаниям быстрее адаптироваться к различным технологическим стекам.

Создание проекта

Для создания нашей библиотеки нам понадобится httpx и asyncio.

Проект будет иметь следующую структуру:

asynclientmts/
    /venv
    /asynclientmts
        __init__.py
        asynclientmts.py
    README.md
    setup.py

Файл setup.py будет установливать нашу бибилотеку через pip, однако об этом немного ниже.

Для начала создадим packages и в нём модуль asynclient.py, который будет содержать наш класс AsyncClientMTS:

class AsyncClientMTS:
	"""The client knows how to make a request to the MTC API."""

	def __init__(
        	self,
    	base_url: str,
    	token: str,
    	aclient: httpx.AsyncClient or None = None
	):
    	"""
    	:param base_url: API URL
    	:param token: Token from MTS
    	:param aclient: Asynchronous client
    	"""
    		self.base_url = base_url
    		self.token = token


    		self.aclient = aclient or httpx.AsyncClient()
    		self.headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {self.token}"}


	async def get_list_sms(self, body={}) -> dict:
    	"""
    	Get a list of all sent messages.

    	:param body: Request body with parameters (can be empty)
    	:return: List with information for each message
    	"""

    		response = await self.aclient.post(url=f"{self.base_url}GetList", json=body, headers=self.headers, timeout=5)
    		response.raise_for_status()
    		decoded_response = response.json()
    		if response.status_code == 200:
        		return decoded_response

Класс AsyncClientMTS имеет следующие особенности:

• Конструктор класса принимает базовый URL API (base_url), токен (token) и асинхронный клиент (aclient). Если асинхронный клиент не предоставлен, создаётся новый экземпляр httpx.AsyncClient.

• Метод get_list_sms выполняет асинхронный POST-запрос к API MTC для получения списка отправленных сообщений. Он принимает тело запроса (body) в формате JSON и возвращает список с информацией по каждому сообщению.

Этот класс позволяет вам легко взаимодействовать с API MTC Exolve, выполнять запросы и получать результаты в асинхронном режиме. Для нашего примера мы использовали один метод из API. Это сделано для простоты и краткости. Если в реальности делать подобную библиотеку, то, конечно, необходимо добавить все методы, которые содержит API. Теперь необходимо упаковать наш модуль в библиотеку, и для этого понадобится setuptools.

Упаковка пакета

Перейдём в файл setup.py.

setup.py — это основной скрипт в Python, который используется для распространения и установки модулей. Этот файл позволяет корректно установить Python пакет на другой компьютер или в другую среду разработки. 

from setuptools import setup
import io

with io.open('README.md', encoding="utf-8") as f:
	result_description = f.read()

setup(
	name='asynclientmts',
	version='1.0',
	packages=['asynclientmts'],
	url='https://<your repo name>.git',
	author='<your name>',
	author_email='<your email>',
	description='The asyncclientmts software package is a client for making asynchronous requests to the MTC API. '
            	'This capability allows you to interact with the MTC API and perform various operations. '
            	'The asyncclientmts module contains the AsyncClientMTS class, '
            	'which provides a convenient interface for working with the MTC API, '
            	'making it easy to execute requests and receive results asynchronously.',
	python_requires='>=3.8',
	install_requires=['anyio==4.3.0',
                  	'certifi==2024.2.2',
                  	'exceptiongroup==1.2.0',
                  	'h11==0.14.0',
                  	'httpcore==1.0.5',
                  	'httpx==0.27.0',
                  	'idna==3.7',
                  	'sniffio==1.3.1',
                  	'typing_extensions==4.11.0'],
	long_description=result_description,
	license='MIT'
)

Функция setup() принимает большое количество именованных аргументов для управления многими аспектами установки пакета и запуска различных команд. Многие аргументы указывают метаданные, используемые для поиска и фильтрации, при загрузке пакета в репозиторий.

Расскажу про основные из них:

• name — название вашей библиотеки;

• version — версия вашей библиотеки;

• packages — список пакетов, включаемых в вашу библиотеку;

• url — URL-адрес репозитория библиотеки;

• author — имя автора;

• author_email — email автора библиотеки;

• description — краткое описание библиотеки;

• python_requires — версия Python, необходимая для работы вашей библиотеки;

• install_requires — список сторонних зависимостей, необходимых для работы нашей библиотеки;

• long_description — подробное описание вашей библиотеки;

• license — лицензия, под которой распространяется ваша библиотека.

В поле license указан тип MIT, это указывает на открытую лицензию, которая позволяет свободное использование, изменение и распространение программного обеспечения. Лицензию разработал Массачусетский технологический институт,  она широко используется в индустрии ПО. 

Помимо неё существуют ещё несколько типов основных лицензий:

• BSD. Лицензия также свободная и открытая. Она предоставляет большую свободу использования, изменения и распространения кода. Однако она отличается в отношении требований к сохранению авторских прав и отказу от гарантий.

• General Public License (GPL). Лицензия копилефтная, поэтому обеспечивает свободу использования, изменения и распространения кода. Одно из основных отличий GPL заключается в том, что она требует, чтобы производные работы, созданные на основе кода с лицензией GPL, также распространялись под лицензией GPL.

• Apache LicenseЛицензия Apache тоже свободная и открытая. Она предоставляет большую свободу использования, изменения и распространения кода. Одним из отличий лицензии Apache является её фокус на защите прав исходного кода и предоставление ясных указаний по патентным вопросам.

В нашем случае long_description подгружаем из файла README.md, который используется для описания в проекта публичном репозитории. Данный файл, помимо описания, будет включать и примеры использования, и способ установки.

Описание для README.md возьмём из поля description и дополним его текстом.

### Install

```pip install git+https://<your repo name>.git```

### Usage example

```commandline


from asynclientmts.asynclientmtst import AsyncClientMTS

if __name__ == "__main__":


	BASE_URL ='https://api.exolve.ru/messaging/v1/'
	API_KEY = <your token from MTS>


	async def amain():
    		async with httpx.AsyncClient() as aclient:
        			client_async = AsyncClientMTS(
            		base_url=BASE_URL,
            		token=API_KEY,
            		aclient=httpx.AsyncClient()
        		)
        		tasks = [
            		client_async.get_list_sms(),
        		]
        		result_work_send = await asyncio.gather(*tasks)

    		return result_work_send


	result = asyncio.run(amain())
	print(result)
```

Наш проект-библиотека готов.

Теперь необходимо загрузить его на gitlab или github, обязательно сделав репозиторий публичным, и с помощью команды:

pip install git+https://<your repo name>.git

мы сможем его свободно загружать в любой проект.

Однако есть особенность: для установки библиотеки в другой проект необходимо указать адрес репозитория. Чтобы библиотеку устанавливать без указания адреса, её необходимо загрузить в PyPI.

PyPI — каталог свободно распространяемых библиотек, написанных на языке Python.

Перед тем как будет возможность разметить наш пакет в каталоге PyPI, вам необходимо на нём зарегистрироваться в качестве разработчика. Далее в наш проект необходимо добавить файл setup.cfg. Этот файл конфигурационный, для хранения настроек библиотеки. В данном примере у нас настроек не будет, поэтому просто вставляем в него следующее:

[egg_info]
tag_build =
tag_date = 0

Установим дополнительную утилиту twine для загрузки на PyPI командой:

pip install twine

Далее перейдём в корневой каталог проекта и запустим команду:

python setup.py sdist

В каталоге проекта появится папка dist и папка asynclientmts.egg-info. Эти папки обязательно добавляем в gitignore.

В конце вводим в терминале команду:

twine upload dist/*

При загрузке в каталог необходимо ввести логин и пароль от аккаунта на PyPI.

Заключение

В итоге создание библиотек для ускорения интеграции с API — эффективная практика, которая помогает крупным компаниям продвигать свои услуги. Благодаря готовым решениям программисты могут сэкономить время и ресурсы, ускорить разработку и старт продукта, а также повысить гибкость и универсальность своих проектов. Благодаря библиотеке разработчики смогут миновать стадию реализации сложной логики взаимодействия с API и сконцентрировать усилия непосредственно на реализации программы. Это позволяет упростить процесс интеграции и снизить количество ошибок. 

Компания может создать библиотеки и для других языков программирования, таких как С#, C, Java, JS, чтобы интеграторы услуг смогли сосредоточится на бизнес-логике своих приложений, вместо того чтобы тратить время на реализацию методов работы с API. Плюс ко всему есть возможность сразу ввести в библиотеку ограничения на определенные действия, такие число запросов в минуту, в день и так далее.

Также важно отметить, что нет необходимости обязательно распространять пакеты публично. Можно сделать закрытый репозиторий для установки библиотеки и не выкладывать её в публичное пространство, а предоставлять доступ к репозиторию только зарегистрированным партнёрам.