Interacting with the API

Performing a `search()`

Using the search() method, you can query any API endpoint for data about an individual or list of items:

From the Docs…

Client.search(endpoint)[source]View on GitHub

Initializes and returns a SearchQuery corresponding to the specified endpoint

Note

Several endpoints have predefined SearchQuery and Model subclasses

If a subclass hasn’t been defined for the endpoint yet, a general SearchQuery will be returned, which wraps the result with APIResponse

Parameters: endpoint (str) – a valid Magento API search endpoint
Return type: SearchQuery

The following Client attributes correspond to endpoint-specific SearchQuery objects:

`Client.orders`	Initializes an `OrderSearch` for the `orders` endpoint
`Client.order_items`	Initializes an `OrderItemSearch` for the `orders/items` endpoint
`Client.invoices`	Initializes an `InvoiceSearch` for the `invoices` endpoint
`Client.products`	Initializes a `ProductSearch` for the `products` endpoint
`Client.product_attributes`	Initializes a `ProductAttributeSearch` for the `products/attributes` endpoint
`Client.categories`	Initializes a `CategorySearch` for the `categories` endpoint

…

Example: search() an endpoint

# Query the "orders" endpoint
>>> api.search("orders")  # api.orders
<magento.search.OrderSearch object at 0x000001EB74FF4DC0>

# Query an endpoint without a predefined SearchQuery
>>> api.search("customers/addresses")
<magento.search.SearchQuery object at 0x000001EB75482F20>

For endpoints with no SearchQuery and Model defined, the APIResponse is used as the wrapper class:

# APIResponse wraps the result when the endpoint has no Model
>>> address = api.search("customers/addresses").by_id(1)
>>> print(address)
<magento.models.model.APIResponse object at 0x00000260A5F2B340>

>>> print(address.region)
{'region_code': 'MI', 'region': 'Michigan', 'region_id': 33}

…

Search Results as Models

The result data of any query is parsed and wrapped by the endpoint’s corresponding Model, making it easier to interact with

# Retrieve product by sku
>>> product = api.products.by_sku("24-MB01")
>>> print(product)
<Magento Product: 24-MB01>

>>> print(f'Name: {product.name} | Price: {product.price}')
Name: Joust Duffle Bag | Price: 99

>>> product.categories
[<Magento Category: Gear>, <Magento Category: Bags>]

>>> product.media_gallery_entries
[<MediaEntry 3417 for <Magento Product: 24-MB01>: Front View>, <MediaEntry 1 for <Magento Product: 24-MB01>: Side View>, ...]

Model Methods

The Model classes have methods to update their data on the store, as well as to search for related items

Example: Retrieving every Order containing a Product

Using the same product from above, we can search for orders as follows

# Using the Product itself
>>> product.get_orders()

[<Magento Order: "#000000003" placed on 2022-12-21 08:09:33>, ... ]

# Using an OrderSearch
>>> api.orders.by_product(product)
>>> api.orders.by_product_id(product.id)
>>> api.orders.by_sku(product.sku)

[<Magento Order: "#000000003" placed on 2022-12-21 08:09:33>, ... ]

Example: Retrieving a Category and related Models

# Get Category data
>>> category = api.categories.by_name("Watches")
>>> category.get_products()
[<Magento Product: 24-MG04>, <Magento Product: 24-MG01>, <Magento Product: 24-MG03>, ... ]

>>> category.get_invoices()
[<Magento Invoice: "#000000004"> for <Magento Order: "#000000004" placed on 2022-11-14 03:27:33>, ... ]

The Model subclasses also have various methods to update data on the store, with scoping taken into account

# Update Product Stock
>>> product.update_stock(3)
|[ MyMagento | website_username ]|:  Updated stock to 4 for <Magento Product: 24-MB01>

# Update thumbnail label on specific store view
>>> product.thumbnail.set_alt_text('Thumbnail on "EN" store view', scope='EN')
>>> print(product.thumbnail)
<MediaEntry 3417 for <Magento Product: 24-MB01>: Thumbnail on "EN" store view>

…

Building Custom Search Queries

In addition to the predefined methods, you can build your own queries too – simply add_criteria(), restrict_fields(), and execute() the search

Example

# Retrieve orders placed since the start of 2023
>>> api.orders.add_criteria(
...    field="created_at",
...    value="2023-01-01",
...    condition="gteq"
... ).execute()

[<Magento Order: "#000000012" placed on 2023-01-02 05:19:55>, <Magento Order: "#000000013" placed on 2023-01-05 09:24:13>]

…

Making Raw Requests

The Client can also be used to generate the url_for() any API endpoint, including a store scope

# Generate the url for credit memo with id 7
>>> api.url_for('creditmemo/7')
"https://website.com/rest/V1/creditmemo/7"

# Generate the same url on the "en" store view
>>> api.url_for('creditmemo/7', scope='en')
"https://domain.com/rest/en/V1/creditmemo/7"

An authorized get(), post(), put(), or delete() request can be made to any endpoint url

>>> response = api.get(api.url_for('creditmemo/7'))
>>> print(response.json())

{'adjustment': 1.5, 'adjustment_negative': 0, 'adjustment_positive': 1.5, 'base_adjustment': 1.5,  ... }