Skip to content

usage.md

Latest commit

 

History

History
158 lines (106 loc) · 3.33 KB

usage.md

File metadata and controls

158 lines (106 loc) · 3.33 KB

Usage

This guide is for developers who need to install the library, configure the client, and use its sync or async APIs in their own code.

Installation

Install the package with pip or uv:

pip install mpt-api-client
uv add mpt-api-client

Prerequisites

  • Python 3.12+
  • Access to an MPT API base URL
  • An MPT API token

Configuration

The client reads configuration from constructor arguments or the environment.

Environment variables:

Variable Required Description
MPT_API_BASE_URL yes SoftwareONE Marketplace API URL
MPT_API_TOKEN yes SoftwareONE Marketplace API token

Example .env snippet:

MPT_API_BASE_URL=<YOUR_MPT_API_BASE_URL>
MPT_API_TOKEN=<YOUR_API_TOKEN>

Instantiate The Client

You can rely on environment variables:

from mpt_api_client import MPTClient

client = MPTClient()

Or pass configuration explicitly:

from mpt_api_client import MPTClient

client = MPTClient.from_config(
    api_token="token",
    base_url="https://api.s1.show/public",
)

Synchronous Usage Patterns

Read a single resource:

from mpt_api_client import MPTClient

client = MPTClient()

product = client.catalog.products.get("PRD-123-456")
print(product.name)

Iterate through a collection:

from mpt_api_client import MPTClient

client = MPTClient()

for invoice in client.billing.invoices.iterate():
    print(invoice.id)

Asynchronous Usage Patterns

import asyncio

from mpt_api_client import AsyncMPTClient


async def main():
    client = AsyncMPTClient()

    product = await client.catalog.products.get("PRD-123-456")
    print(product.name)

    async for item in client.catalog.products.iterate():
        print(item.id, item.name)


asyncio.run(main())

Navigate The API Surface

The client exposes resource groups such as:

  • client.accounts
  • client.audit
  • client.billing
  • client.catalog
  • client.commerce
  • client.exchange
  • client.helpdesk
  • client.integration
  • client.notifications

See architecture.md for the repository structure and the MPT OpenAPI spec for the upstream endpoint contract.

Filtering And Querying

Use filter(), order_by(), and select() on queryable resources.

The full RQL syntax and builder usage are documented in rql.md. Treat that file as the source of truth for query composition.

Typical example:

from mpt_api_client import MPTClient, RQLQuery

client = MPTClient()

target_ids = RQLQuery("id").in_(["PRD-123-456", "PRD-789-012"])
active = RQLQuery(status="active")
vendor = RQLQuery("vendor.name").eq("Microsoft")

query = target_ids & active & vendor

for product in (
    client.catalog.products
    .filter(query)
    .order_by("-audit.updated.at")
    .select("id", "name")
    .iterate()
):
    print(product.id, product.name)

Related Documents