Overview
Recomax provides a RESTful API for managing shops, events, items, and users. This API is designed to facilitate seamless interactions between e-commerce platforms and recommendation engines.
Base URL
Resources
Shops
The shops resource represents individual stores and contains endpoints for managing events, items, and users.
Events
/shops/{shopId}/events
List Events
Endpoint: GET /shops/{shopId}/events
Description: Retrieves a paginated list of events associated with a shop.
Query Parameters:
filter (string, default {}) – Filters events based on criteria.
pageNo (integer, default 0) – Specifies the page number.
pageSize (integer, default 50) – Defines the number of results per page.
sortDirection (string, default asc) – Sorting order (asc, desc).
Response:
{
"currentPage": 1,
"totalEvents": 100,
"events": [...]
}Add Event
Endpoint: POST /shops/{shopId}/events
Description: Adds a new event to the shop.
Request Body:
{
"eventId": "evt123",
"name": "Item Viewed",
"userId": "user456",
"item": { "itemId": "item789" }
}Response:
{
"status": "success",
"message": "Event added successfully"
}Items
/shops/{shopId}/items
List Items
Endpoint: GET /shops/{shopId}/items
Description: Retrieves a list of items in a shop.
Query Parameters:
filter (string, default {}) – Filters items.
pageNo (integer, default 0) – Page number.
pageSize (integer, default 50) – Number of results per page.
Response:
{
"currentPage": 1,
"totalItems": 500,
"items": [...]
}Add Item
Endpoint: POST /shops/{shopId}/items
Description: Adds a new item to the shop.
Request Body:
{
"itemId": "item123",
"attributes": { "color": "red", "size": "M" }
}Response:
{
"status": "success",
"message": "Item added successfully"
}Users
/shops/{shopId}/users
List Users
Endpoint: GET /shops/{shopId}/users
Description: Retrieves a list of users associated with a shop.
Query Parameters:
eventFilter (string, default {}) – Filters users based on events.
pageNo (integer, default 0) – Page number.
pageSize (integer, default 50) – Number of results per page.
Response:
{
"currentPage": 1,
"totalUsers": 200,
"users": [...]
}Add User
Endpoint: POST /shops/{shopId}/users
Description: Adds a new user to the shop.
Request Body:
{
"userId": "user123",
"email": "user@example.com"
}Response:
{
"status": "success",
"message": "User added successfully"
}Authentication
This API requires authentication for all endpoints. Ensure that requests include a valid API key or token.
Error Handling
401 Unauthorized – The request lacks valid authentication credentials.
403 Forbidden – The user does not have permission to access this resource.
404 Not Found – The requested resource does not exist.
Conclusion
The Recomax API provides a structured way to manage shops, events, items, and users, enabling seamless integration with recommendation systems.