π What's MyMagento? |
---|
|
If you've worked with the Magento 2 API, you'll know that not all endpoints are created equally.
MyMagento
aims to streamline your workflow by simplifying a variety of commonly needed API operations.
...
π» The |
---|
|
π The |
---|
|
π§ The |
---|
|
...
MyMagento
is compatible with every API endpoint_
Endpoints are wrapped with a Model
_ and SearchQuery
_ subclass as follows:
Endpoint | Client Shortcut | SearchQuery _ Subclass |
Model _ Subclass |
---|---|---|---|
orders |
Client.orders _ |
OrderSearch _ |
Order _ |
orders/items |
Client.order_items _ |
OrderItemSearch _ |
OrderItem _ |
invoices |
Client.invoices _ |
InvoiceSearch _ |
Invoice _ |
products |
Client.products _ |
ProductSearch _ |
Product _ |
products/attributes |
Client.product_attributes _ |
ProductAttributeSearch _ |
ProductAttribute _ |
categories |
Client.categories _ |
CategorySearch _ |
Category _ |
customers |
Client.customers _ |
CustomerSearch _ |
Customer _ |
endpoint |
Client.search('endpoint') |
SearchQuery _ |
APIResponse _ |
...
To install using pip
:
pip install my-magento
Please note that MyMagento
requires Python >= 3.10
...
Full documentation can be found on ReadTheDocs
MyMagento
uses the Client
_ class to handle all interactions with the API.
π‘ Tip |
---|
See Get a Magento 2 REST API Token With MyMagento for full details on generating an access token |
To generate an ACCESS_TOKEN
_ you'll need to authenticate()
_ your USER_CREDENTIALS
_.
Creating a Client
_ requires a domain
, username
, and password
at minimum.
>>> domain = 'website.com'
>>> username ='username'
>>> password = 'password'
If you're using a local installation of Magento you'll need to set local=True
. Your domain should look like this:
>>> domain = '127.0.0.1/path/to/magento'
...
from magento import Client
>>> api = Client(domain, username, password, **kwargs)
import magento
>>> api = magento.get_api(**kwargs)
get_api()
_ takes the same keyword arguments as the Client
_
- If the
domain
,username
, orpassword
are missing, it will attempt to use the following environment variables:
import os
os.environ['MAGENTO_DOMAIN'] = domain
os.environ['MAGENTO_USERNAME']= username
os.environ['MAGENTO_PASSWORD']= password
...
Unless you specify login=False
, the Client
_ will automatically call authenticate()
_ once initialized:
>> api.authenticate()
|[ MyMagento | website_username ]|: Authenticating username on website.com...
|[ MyMagento | website_username ]|: Logged in to username
The Client.search()
_ method lets you execute()
_ a query on any API endpoint_
It creates a SearchQuery
_ for the endpoint, allowing you to retrieve data about
- An individual item (ex.
by_id()
_) - A list of items (ex.
by_list()
_) - Any search criteria you desire (see Building Custom Search Queries)
...
# Query the "invoices" endpoint (also: api.invoices)
>>> api.search("invoices").by_id(1)
<Magento Invoice: "#000000001"> for <Magento Order: "#000000001" placed on 2022-11-01 03:27:33>
# 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>, ...]
...
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.
Let's retrieve a Product
_ using by_sku()
_
>>> product = api.products.by_sku("24-MB01")
We can search for orders containing this product in multiple ways:
# 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>, ... ]
>>> 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>, ... ]
# 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
|
...
In addition to the predefined methods, you can also build your own queries
- Simply
add_criteria()
_,restrict_fields()
_, andexecute()
_ the search - The
since()
_ anduntil()
_ 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()
[<Magento Order: "#000000012" placed on 2023-01-02 05:19:55>, ...] |
...
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.
# 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 |
---|
A # Retrieve credit memo with id 7 using a search
>>> memo = api.search("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> |