interact-with-api.rst

Performing a search()

The search() method lets you execute_search() a query on any API endpoint

It creates a SearchQuery for the endpoint, allowing you to retrieve data for

• An individual item (ex. by_id())
• A list of items (ex. by_list())
• Any search criteria you desire (see Building Custom Search Queries)

📚 From the Docs...
Client.search(endpoint) 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

Example: search() an endpoint by_id()

# Query the "invoices" endpoint (also: api.invoices)
>>> api.manager("invoices").by_id(1)

<Magento Invoice: "#000000001"> for <Magento Order: "#000000001" placed on 2022-11-01 03:27:33>

Example: search() an endpoint by_list()

# Retrieve invoices from a list of invoice ids
>>> ids = list(range(1,101))
>>> api.invoices.by_list("entity_id", ids)

[<Magento Invoice: "#000000001"> for <Magento Order: "#000000001" placed on 2022-11-01 03:27:33>, ...]

Search Results: The Model Classes

The result of any SearchQuery will be parsed and wrapped by a Model class in the magento.models subpackage.

These classes make the API response data easier to work with.

They also provide endpoint-specific methods to update store data and search for related items.

Example: Retrieving every Order containing a Product

Let's retrieve a Product using by_sku()

>>> product = api.products.by_sku("24-MB01")

We can search for orders containing this product 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 some items related to a Category

# Get Category data
>>> category = api.categories.by_name("Watches")
>>> category.get_products()
>>> category.get_invoices()

[<Magento Product: 24-MG04>, <Magento Product: 24-MG01>, <Magento Product: 24-MG03>, ... ]
[<Magento Invoice: "#000000004"> for <Magento Order: "#000000004" placed on 2022-11-14 03:27:33>, ... ]

Example: Updating the Thumbnail MediaEntry of a Product

 # Update product thumbnail label on specific store view
>>> product.thumbnail.set_alt_text("bonjour", scope="FR")
>>> print(product.thumbnail)

 <MediaEntry 3417 for <Magento Product: 24-MB01>: bonjour>

💡 Tip: Set the Store Scope
If you have multiple store views, a store_code can be specified when retrieving/updating data The Client.scope is used by default - simply change it to switch store views Passing the scope keyword argument to url_for(), Model.refresh(), and some Model update methods (like set_alt_text() above) will temporarily override the Client's scope

Building Custom Search Queries

In addition to the predefined methods, you can also build your own queries

• Simply add_criteria(), restrict_fields(), and execute_search() the search
• The since() and until() methods allow you to further filter your query by date

📄 Example: Retrieve Orders Over $50 Placed Since the Start of 2023
>>> api.orders.add_criteria( ... field="grand_total", ... value="50", ... condition="gt" ... ).since("2023-01-01").execute_search() [<Magento Order: "#000000012" placed on 2023-01-02 05:19:55>, <Magento Order: "#000000013" placed on 2023-01-05 09:24:13>]

Making Authorized Requests

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

You can use this URL to make an authorized get(), post(), put(), or delete() request

Example: Making a get() Request

# Request the data for credit memo with id 7
>>> url = api.url_for('creditmemo/7')
>>> response = api.get(url)
>>> print(response.json())

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

📝 Note

Using a search() is simpler than making get() requests, since the result is wrapped by APIResponse or other Model # Retrieve credit memo with id 7 using a search >>> memo = api.manager("creditmemo").by_id(7) >>> print(memo.data) >>> print(memo) {'adjustment': 1.5, 'adjustment_negative': 0, 'adjustment_positive': 1.5, 'base_adjustment': 1.5, ... } <magento.models.model.APIResponse object at 0x000001BA42FD0FD1>