API Documentation for Recommendation Engine

Overview

This documentation describes the APIs for a Recommendation Engine that provides product recommendations, learns from user sessions, and trains its recommendation model. The API is designed to be RESTful and responds with JSON-formatted data.

Base URL

The base URL for all API endpoints is https://api.appengine.co.uk/recomengine/v1.0/

Authentication

Each request must include an account_id parameter that uniquely identifies the client.

Endpoints

1. Get Recommendations

  • URL: /recommend/
  • Method: GET
  • Description: Retrieves product recommendations based on the specified product ID.
  • Query Parameters:
    • account_id: The unique identifier for the client’s account.
    • product_id: The product ID for which recommendations are sought.
  • Success Response:
    • Code: 200 OK
    • Content:jsonCopy code{ "account_id": "example_account_id", "product_id": "example_product_id", "recommended_products": ["prod123", "prod456", "prod789"] }
  • Error Response:
    • Code: 400 Bad Request
    • Content:jsonCopy code{ "error": "Missing or invalid parameters." }
  • Sample Call:bashCopy codecurl -X GET "https://api.appengine.co.uk/recomengine/v1.0/recommend/?account_id=example_account_id&product_id=example_product_id"

2. Learn from User Sessions

  • URL: /learn/
  • Method: GET
  • Description: Processes user session data to update product co-occurrences.
  • Query Parameters:
    • account_id: The unique identifier for the client’s account.
    • session_id: Session identifier for the user session.
    • product_ids: Comma-separated list of product IDs observed in the session.
  • Success Response:
    • Code: 200 OK
    • Content:jsonCopy code{ "account_id": "example_account_id", "output": "Matrix Updated", "products_processed": 3, "new_products_added": 1, "execution_time_seconds": 0.512 }
  • Error Response:
    • Code: 400 Bad Request
    • Content:jsonCopy code{ "error": "Missing or invalid parameters." }
  • Sample Call:bashCopy codecurl -X GET "https://api.appengine.co.uk/recomengine/v1.0/learn/?account_id=example_account_id&session_id=session123&product_ids=prod123,prod456,prod789"

3. Train Recommendation Model

  • URL: /train/
  • Method: GET
  • Description: Initiates the training of the recommendation model using available data.
  • Query Parameters:
    • account_id: The unique identifier for the client’s account.
  • Success Response:
    • Code: 200 OK
    • Content:jsonCopy code{ "account_id": "example_account_id", "output": "Training complete." }
  • Error Response:
    • Code: 400 Bad Request
    • Content:jsonCopy code{ "error": "Missing or invalid account_id parameter." }
  • Sample Call:bashCopy codecurl -X GET "https://api.appengine.co.uk/recomengine/v1.0/train/?account_id=example_account_id"