OpenMage JSON-RPC API Overview¶
Introduction¶
The OpenMage API provides a standardized interface for third-party applications to interact with your OpenMage store. Using the API, developers can create applications that can:
- Manage products, categories, and inventory
- Process orders and shipments
- Handle customer data
- Access sales and catalog information
- And much more
This document focuses on the JSON-RPC implementation of the OpenMage API, which provides a lightweight, language-agnostic way to interact with your OpenMage store programmatically.
API Architecture Overview¶
The OpenMage API is built on a modular architecture that supports multiple protocols:
- JSON-RPC: A lightweight protocol that uses JSON for data encoding
- XML-RPC: Similar to JSON-RPC but uses XML for data encoding
- SOAP: A comprehensive web service protocol with formal WSDL definitions
- REST: See OpenMage REST API for more information
The JSON-RPC adapter is implemented in Mage_Api_Model_Server_Adapter_Jsonrpc
and uses the Zend_Json_Server
component to handle requests and responses. The API follows a resource-based architecture where functionality is organized into logical resources (like catalog, customer, sales) with methods that operate on those resources.
Key Components¶
- API Entry Point: The
api.php
file serves as the entry point for all API requests, routed to by the web server using the/api/jsonrpc
URL - Server Adapter: Handles protocol-specific details (JSON-RPC, XML-RPC, SOAP)
- Handler: Processes API requests and maps them to the appropriate resource models
- Resource Models: Implement the actual business logic for API operations
- ACL (Access Control List): Controls access to resources based on user permissions
Authentication¶
To use the OpenMage API, you must either authenticate with the login method to obtain a session ID and include this session ID with all subsequent API calls, or use the HTTP Basic Authentication method. The HTTP Basic Authentication method allows you to skip the login step and use your API credentials directly in the request which is simpler for many use cases, but does expose your credentials in each request whereas the session ID expires and needs to be refreshed periodically.
Login Authentication Process¶
- Create an API User: In the OpenMage admin panel, go to System > Web Services > SOAP/XML-RPC - Users to create a user with appropriate role permissions
- Login Request: Send a login request with your username and API key
- Session ID: Receive a session ID that will be used for all subsequent requests
- Session Expiration: Sessions expire after a period of inactivity (configurable in OpenMage settings)
Login Authentication Example¶
// Login Request
{
"jsonrpc": "2.0",
"method": "login",
"params": ["apiuser", "apikey123"],
"id": 1
}
// Login Response
{
"jsonrpc": "2.0",
"result": "8b98a77a37f50d3d472302981e86aab2",
"id": 1
}
HTTP Basic Authentication¶
As an alternative to session-based authentication, OpenMage also supports HTTP Basic Authentication for API requests. This method simplifies the authentication process by eliminating the need for a separate login step.
How HTTP Basic Authorization Works¶
- Use API Credentials: The API username and API key (created in admin panel) are used as the username and password for HTTP Basic Authorization
- Skip Login Call: When using HTTP Basic Authorization, the “login” call is not required
- Null Session ID: The session ID parameter in the “call” method can be set to “null”
- Include Authorization Header: Include the Authorization header with each request
HTTP Basic Authorization Example¶
<?php
// PHP example using HTTP Basic Authorization
$jsonRpcUrl = 'https://your-magento-store.com/api/jsonrpc';
$apiUser = 'apiuser';
$apiKey = 'apikey123';
// Request data with null session ID
$requestData = array(
'jsonrpc' => '2.0',
'method' => 'call',
'params' => [
null, // Null session ID when using HTTP Basic Authorization
'catalog_product.info',
'product_sku_123'
],
'id' => 1
);
$ch = curl_init($jsonRpcUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_USERPWD, "$apiUser:$apiKey"); // HTTP Basic Authorization
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($requestData));
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
print_r($result['result']);
?>
JSON-RPC 2.0 Request/Response Format¶
The OpenMage API implements the JSON-RPC 2.0 specification, which defines a stateless (aside from the session id), light-weight remote procedure call (RPC) protocol using JSON as the data format.
Request Format¶
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"resource.method",
[param1, param2, ...]
],
"id": request_id
}
jsonrpc
: Must be exactly “2.0”method
: For most API calls, this will be “call”params
: An array containing:- The session ID obtained from login or
null
for HTTP Basic Authorization - The resource and method name in the format “resource.method”
- An array of parameters for the method
id
: A unique identifier for the request (can be a string or number)
Response Format¶
jsonrpc
: Always “2.0”result
: The data returned by the method callid
: The same ID that was sent in the request
Error Response Format¶
Error Handling¶
The OpenMage API uses standardized error codes and messages to communicate issues with API requests.
Common Error Codes¶
Code | Message | Description |
---|---|---|
0 | Unknown Error | A general error occurred |
1 | Internal Error | An internal server error occurred |
2 | Access denied | Authentication failed or insufficient permissions |
3 | Invalid API path | The requested resource or method doesn’t exist |
4 | Resource path is not callable | The requested method cannot be called |
5 | Session expired | The session has expired, need to login again |
6 | Invalid request parameter | A required parameter is missing or invalid |
HTTP Status Codes¶
The API also uses HTTP status codes to indicate the status of requests:
- 200 OK: Request successful
- 400 Bad Request: Invalid request parameters
- 401 Unauthorized: Authentication required
- 403 Forbidden: Access denied
- 404 Not Found: Resource not found
- 500 Internal Server Error: Server-side error
Common Usage Patterns¶
Basic Workflow¶
- Authentication: Login to obtain a session ID
- API Calls: Make one or more API calls using the session ID
- End Session: Optionally end the session when finished
Batch Operations with multiCall
¶
For improved performance when making multiple API calls, use the multiCall
method to batch requests:
{
"jsonrpc": "2.0",
"method": "multiCall",
"params": [
"session_id",
[
["catalog_product.list", [filter_parameters]],
["catalog_product.info", [product_id]]
]
],
"id": 1
}
Error Handling Best Practices¶
- Always check for errors in API responses
- Implement retry logic for transient errors
- Handle session expiration by re-authenticating
- Log detailed error information for troubleshooting
Code Examples¶
Authentication¶
<?php
// PHP example of authentication
$jsonRpcUrl = 'https://your-magento-store.com/api/jsonrpc';
$userData = array(
'jsonrpc' => '2.0',
'method' => 'login',
'params' => ['apiuser', 'apikey123'],
'id' => 1
);
$ch = curl_init($jsonRpcUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($userData));
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
$sessionId = $result['result'];
echo "Session ID: " . $sessionId;
?>
Retrieving Product Information¶
<?php
// PHP example of retrieving product information
$sessionId = '8b98a77a37f50d3d472302981e86aab2'; // From login response
$jsonRpcUrl = 'https://your-magento-store.com/api/jsonrpc';
$requestData = array(
'jsonrpc' => '2.0',
'method' => 'call',
'params' => [
$sessionId,
'catalog_product.info',
'product_sku_123'
],
'id' => 2
);
$ch = curl_init($jsonRpcUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($requestData));
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
print_r($result['result']);
?>
Creating a New Product¶
<?php
// PHP example of creating a new product
$sessionId = '8b98a77a37f50d3d472302981e86aab2'; // From login response
$jsonRpcUrl = 'https://your-magento-store.com/api/jsonrpc';
$productData = array(
'type_id' => 'simple',
'attribute_set_id' => 4,
'sku' => 'new_product_123',
'name' => 'New Test Product',
'price' => 99.99,
'status' => 1,
'weight' => 1.0,
'visibility' => 4,
'description' => 'Product description here',
'short_description' => 'Short description',
'stock_data' => array(
'qty' => 100,
'is_in_stock' => 1
)
);
$requestData = array(
'jsonrpc' => '2.0',
'method' => 'call',
'params' => [
$sessionId,
'catalog_product.create',
['simple', 4, 'new_product_123', $productData]
],
'id' => 3
);
$ch = curl_init($jsonRpcUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($requestData));
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
echo "Product ID: " . $result['result'];
?>
Available Resources¶
The OpenMage API provides access to numerous resources and third-party extensions may also provide additional resources. Please refer to the individual resource documentation pages in the left sidebar for more information on available methods and parameters.
Best Practices¶
- Use HTTPS: Always use HTTPS for API calls to ensure secure communication
- Implement Rate Limiting: Avoid overwhelming the server with too many requests
- Cache Responses: Cache responses when appropriate to reduce API calls
- Handle Errors Gracefully: Implement proper error handling in your applications
- Use Batch Operations: Use
multiCall
for better performance when making multiple requests - Validate Input: Always validate input data before sending it to the API
- Monitor API Usage: Keep track of API usage to identify potential issues
- Keep API Keys Secure: Never expose API keys in client-side code