This document provides comprehensive and detailed professional API documentation for the PantheraHive Widget Management API. It includes endpoint descriptions, request/response examples, authentication guides, and SDK usage examples to help developers quickly integrate and utilize our services.
Welcome to the PantheraHive Widget Management API documentation! This API allows you to programmatically manage your widgets, including creating, retrieving, updating, and deleting them. Our API is designed to be RESTful, predictable, and easy to use, enabling seamless integration with your applications.
* [API Key Authentication](#api-key-authentication)
* [Generating an API Key](#generating-an-api-key)
* [Widget Object](#widget-object)
* [Error Object](#error-object)
* [Widgets](#widgets)
* [GET /widgets](#get-widgets)
* [POST /widgets](#post-widgets)
* [GET /widgets/{widgetId}](#get-widgets-widgetid)
* [PUT /widgets/{widgetId}](#put-widgets-widgetid)
* [DELETE /widgets/{widgetId}](#delete-widgets-widgetid)
* [Python](#python)
* [JavaScript (Node.js)](#javascript-nodejs)
The PantheraHive Widget Management API provides a robust and secure way to interact with your widget resources. You can perform standard CRUD (Create, Read, Update, Delete) operations on individual widgets and manage collections of widgets. All API requests and responses are formatted as JSON.
All API requests should be made to the following base URL:
https://api.pantherahive.com/v1
The PantheraHive Widget Management API uses API Key authentication. All requests to protected endpoints must include your API key in the X-API-Key HTTP header.
To authenticate your requests, include the X-API-Key header with your secret API key.
Example Request Header:
X-API-Key: YOUR_SECRET_API_KEY
This document outlines the detailed architecture plan for a robust, professional API Documentation Generator. The goal is to create a system capable of ingesting various API definitions and generating high-quality, comprehensive, and user-friendly documentation in multiple formats.
Goal: To provide a versatile and automated solution for generating professional API documentation that is clear, accurate, and easy to maintain. It aims to reduce the manual effort involved in documentation, ensure consistency, and improve the developer experience for API consumers.
Vision: A tool that acts as the single source of truth for API documentation, integrating seamlessly into CI/CD pipelines and supporting a wide array of input formats and output styles, ultimately fostering better API adoption and understanding.
The system will be composed of several interconnected modules, each responsible for a specific function:
This layer is responsible for accepting and interpreting various API definition formats.
* Functionality: Reads and validates OpenAPI (v2, v3, v3.1) or Swagger specifications (YAML/JSON).
* Output: Converts the raw specification into a standardized internal data model.
* Key Features: Schema validation, error reporting for malformed definitions.
* Functionality: Ingests additional documentation content (e.g., introduction, getting started guides, tutorials, custom sections) written in Markdown or a similar markup language.
* Output: Parses Markdown into an abstract syntax tree (AST) or structured HTML fragments.
* Key Features: Support for common Markdown extensions (tables, code blocks, admonitions).
* Functionality: Scans source code (e.g., JSDoc, PHPDoc, GoDoc, JavaDoc) to extract endpoint descriptions, parameter details, and example usage directly from comments.
* Output: Structured data to augment or generate parts of the API definition.
* Key Features: Language-specific parsers, configurable annotation patterns.
* Functionality: Reads system-wide and project-specific configuration files (e.g., output formats, branding, template selection, custom fields).
* Output: Configuration objects for the generator core.
This is the central processing unit that transforms parsed input into renderable content.
* Functionality: Consolidates data from all input sources (OpenAPI, Markdown, code annotations, configuration) into a consistent, unified, and technology-agnostic internal data model. This model represents all aspects of the API documentation (endpoints, parameters, responses, authentication, examples, custom pages).
* Key Features: Data merging, conflict resolution, data enrichment (e.g., inferring examples).
* Functionality: Applies predefined or custom templates to the normalized internal data model to generate the final documentation content.
* Key Features: Support for various template languages (e.g., Jinja2, Handlebars), conditional rendering, partials/includes, custom helpers.
* Functionality: Converts structured content (e.g., Markdown AST, internal data model objects) into the desired intermediate format (e.g., HTML fragments).
* Key Features: Syntax highlighting for code examples, Mermaid diagram rendering, mathematical notation support.
This layer is responsible for producing the final documentation in various requested formats.
* Functionality: Generates a complete, self-contained static website for the API documentation.
* Key Features: Responsive design, search functionality, navigation (sidebar, table of contents), customizable themes, integration of external assets (fonts, icons).
* Functionality: Renders the documentation into a printable PDF document.
* Key Features: Customizable cover page, table of contents, pagination, consistent styling with web output.
* Functionality: Exports the entire documentation content back into a structured Markdown format, suitable for Git repositories or other Markdown-based systems.
* Functionality: Integrates with existing tools like Swagger UI or Redoc to display the OpenAPI specification interactively.
* Key Features: Provides "Try It Out" functionality for endpoints.
* Functionality: Publishes generated documentation to a specified Git repository or static hosting service.
A web-based UI or robust CLI for interacting with the generator.
* Functionality: Provides a dashboard for managing API projects, configuring generation settings, previewing documentation, and triggering builds.
* Key Features: Project management, template selection, custom branding upload, live preview, user management (if hosted).
* Functionality: Allows developers to programmatically trigger documentation generation as part of CI/CD pipelines.
* Key Features: Configuration via arguments/files, exit codes for success/failure.
Manages the storage of configurations, templates, and generated outputs.
* Primary Choice: Python with FastAPI (for speed and modern async support) or Django (for comprehensive features and ORM).
* Alternatives: Node.js with Express/NestJS, Go with Gin/Echo, Java with Spring Boot.
* Primary Choice: React or Vue.js (for reactive, component-based UI development).
* Alternatives: Angular.
* Python: openapi-spec-validator, PyYAML.
* Node.js: swagger-parser, js-yaml.
* Python: Jinja2.
* Node.js: Handlebars, Nunjucks.
* Go: text/template, html/template.
* Python: markdown-it-py, CommonMark.
* Node.js: markdown-it.
* wkhtmltopdf (via wrapper like pdfkit in Python) or headless browser solutions like Puppeteer (Node.js) for more control over styling.
* Consider using frameworks like Next.js, Gatsby, or Hugo to serve the generated static HTML efficiently, or generate pure HTML/CSS/JS.
* PostgreSQL (relational, robust) or MongoDB (NoSQL, flexible schema).
asyncio, Node.js event loop) for I/O-bound operations like file parsing and generation.* Compute: AWS ECS/EKS, Azure Kubernetes Service, Google GKE/Cloud Run.
* Database: AWS RDS, Azure SQL Database, Google Cloud SQL.
* Storage: AWS S3, Azure Blob Storage, Google Cloud Storage for generated artifacts.
Important: Keep your API keys secure and never expose them in client-side code, public repositories, or other insecure locations.
You can generate and manage your API keys from your PantheraHive developer dashboard:
The API uses standard HTTP status codes to indicate the success or failure of an API request. In case of an error, the response body will contain a JSON object with more details about the error.
| HTTP Status Code | Meaning | Description
Welcome to the PantheraHive Product Catalog API documentation! This document provides a comprehensive guide to interacting with our Product Catalog API, enabling you to programmatically manage products, retrieve product information, and integrate product data into your applications.
Our API is designed to be RESTful, making it easy to understand and use. All requests and responses are handled in JSON format.
* [API Key](#api-key)
* [Products](#products)
* [GET /products](#get-products)
* [GET /products/{id}](#get-productsid)
* [POST /products](#post-products)
* [Python SDK](#python-sdk)
* [JavaScript SDK](#javascript-sdk)
The PantheraHive Product Catalog API provides a robust interface for managing your product inventory. You can use this API to:
Our goal is to provide a seamless and efficient way to integrate product management into your workflows and applications.
All API requests are made to the base URL:
https://api.pantherahive.com/v1
To use the API, you will need an API Key, which must be included in every request for authentication. See the [Authentication](#3-authentication) section for details.
All requests should use Content-Type: application/json for POST/PUT requests, and responses will also be in JSON format.
The PantheraHive Product Catalog API uses API Key authentication.
To authenticate your requests, you must include your unique API Key in the X-API-Key HTTP header. If the API Key is missing or invalid, the API will return a 401 Unauthorized error.
How to obtain your API Key:
Your API Key can be generated and managed from your PantheraHive developer dashboard under the "API Keys" section. Treat your API Key like a password and keep it secure. Do not expose it in client-side code or public repositories.
Example Request Header:
X-API-Key: YOUR_API_KEY_HERE
Content-Type: application/json
The API uses standard HTTP status codes to indicate the success or failure of an API request. In case of an error, the response body will contain a JSON object with more details about the error.
| Status Code | Meaning | Description | Example Error Response |
| :---------- | :--------------------------- | :------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------- |
| 200 OK | Success | The request was successful. | { "message": "Success", ... } |
| 201 Created | Resource Created | The resource was successfully created. | { "message": "Product created successfully", ... } |
| 400 Bad Request | Invalid Request | The request was malformed or missing required parameters. | { "error": "Bad Request", "details": "Name field is required." } |
| 401 Unauthorized | Authentication Failed | No valid API Key provided, or the API Key is invalid. | { "error": "Unauthorized", "details": "Invalid API Key." } |
| 403 Forbidden | Access Denied | You do not have permission to access the requested resource. | { "error": "Forbidden", "details": "Insufficient permissions." } |
| 404 Not Found | Resource Not Found | The requested resource could not be found. | { "error": "Not Found", "details": "Product with ID 'xyz' not found." } |
| 429 Too Many Requests | Rate Limit Exceeded | You have sent too many requests in a given amount of time. See [Rate Limiting](#7-rate-limiting). | { "error": "Too Many Requests", "details": "Rate limit exceeded. Try again in 60 seconds." } |
| 500 Internal Server Error | Server Error | An unexpected error occurred on the server. Please try again later or contact support. | { "error": "Internal Server Error", "details": "An unexpected error occurred." } |
The /products endpoint allows you to manage your product catalog.
##### GET /products
Retrieves a list of all products in the catalog. You can filter and paginate the results using query parameters.
HTTP Method: GET
Path: /products
Description:
Returns an array of product objects. By default, it returns the first 10 products.
Query Parameters:
| Name | Type | Description | Required | Example |
| :-------- | :------- | :-------------------------------------------------------------------------- | :------- | :----------- |
| limit | integer | Maximum number of products to return. Default is 10, max is 100. | No | limit=20 |
| offset | integer | Number of products to skip before starting to return results. Default is 0. | No | offset=10 |
| category| string | Filter products by category. | No | category=Electronics |
| search | string | Search products by name or description. | No | search=laptop |
Request Example (cURL):
curl -X GET \
'https://api.pantherahive.com/v1/products?limit=2&category=Electronics' \
-H 'X-API-Key: YOUR_API_KEY_HERE'
Request Example (Python):
import requests
api_key = "YOUR_API_KEY_HERE"
base_url = "https://api.pantherahive.com/v1"
headers = {
"X-API-Key": api_key,
"Content-Type": "application/json"
}
params = {
"limit": 2,
"category": "Electronics"
}
response = requests.get(f"{base_url}/products", headers=headers, params=params)
if response.status_code == 200:
print(response.json())
else:
print(f"Error: {response.status_code} - {response.json()}")
Request Example (Node.js):
const fetch = require('node-fetch'); // For Node.js environments
const apiKey = "YOUR_API_KEY_HERE";
const baseUrl = "https://api.pantherahive.com/v1";
async function getProducts() {
const headers = {
"X-API-Key": apiKey,
"Content-Type": "application/json"
};
const params = new URLSearchParams({
limit: 2,
category: "Electronics"
}).toString();
try {
const response = await fetch(`${baseUrl}/products?${params}`, { headers });
const data = await response.json();
if (response.ok) {
console.log(data);
} else {
console.error(`Error: ${response.status} - ${JSON.stringify(data)}`);
}
} catch (error) {
console.error("Network or parsing error:", error);
}
}
getProducts();
Successful Response (200 OK):
[
{
"id": "prod_abc123",
"name": "Panthera Smart Watch",
"description": "A sleek smart watch with health tracking features.",
"price": 199.99,
"category": "Electronics",
"stock": 50,
"created_at": "2023-10-26T10:00:00Z",
"updated_at": "2023-10-26T10:00:00Z"
},
{
"id": "prod_def456",
"name": "Ergonomic Office Chair",
"description": "Comfortable and adjustable chair for long working hours.",
"price": 349.00,
"category": "Furniture",
"stock": 20,
"created_at": "2023-10-25T14:30:00Z",
"updated_at": "2023-10-25T14:30:00Z"
}
]
Error Response (401 Unauthorized):
{
"error": "Unauthorized",
"details": "Invalid API Key."
}
##### GET /products/{id}
Retrieves detailed information for a specific product by its unique ID.
HTTP Method: GET
Path: /products/{id}
Description:
Returns a single product object matching the provided id.
Path Parameters:
| Name | Type | Description | Required | Example |
| :--- | :------- | :---------------------- | :------- | :----------- |
| id | string | The unique ID of the product to retrieve. | Yes | prod_abc123 |
Request Example (cURL):
curl -X GET \
'https://api.pantherahive.com/v1/products/prod_abc123' \
-H 'X-API-Key: YOUR_API_KEY_HERE'
Request Example (Python):
import requests
api_key = "YOUR_API_KEY_HERE"
base_url = "https://api.pantherahive.com/v1"
product_id = "prod_abc123"
headers = {
"X-API-Key": api_key,
"Content-Type": "application/json"
}
response = requests.get(f"{base_url}/products/{product_id}", headers=headers)
if response.status_code == 200:
print(response.json())
else:
print(f"Error: {response.status_code} - {response.json()}")
Request Example (Node.js):
const fetch = require('node-fetch');
const apiKey = "YOUR_API_KEY_HERE";
const baseUrl = "https://api.pantherahive.com/v1";
const productId = "prod_abc123";
async function getProductById() {
const headers = {
"X-API-Key": apiKey,
"Content-Type": "application/json"
};
try {
const response = await fetch(`${baseUrl}/products/${productId}`, { headers });
const data = await response.json();
if (response.ok) {
console.log(data);
} else {
console.error(`Error: ${response.status} - ${JSON.stringify(data)}`);
}
} catch (error) {
console.error("Network or parsing error:", error);
}
}
getProductById();
Successful Response (200 OK):
{
"id": "prod_abc123",
"name": "Panthera Smart Watch",
"description": "A sleek smart watch with health tracking features.",
"price": 199.99,
"category": "Electronics",
"stock": 50,
"created_at": "2023-10-26T10:00:00Z",
"updated_at": "2023-10-26T10:00:00Z"
}
Error Response (404 Not Found):
{
"error": "Not Found",
"details": "Product with ID 'prod_xyz999' not found."
}
##### POST /products
Creates a new product in the catalog.
HTTP Method: POST
Path: /products
Description:
Adds a new product to the catalog. The name, price, and category fields are required. Upon successful creation, returns the newly created product object.
Request Body (JSON):
| Name | Type | Description | Required | Example |
| :---------- | :-------- | :---------------------------------------------- | :------- | :------------- |
| name | string | The name of the product. | Yes | "Wireless Headphones" |
| description| string | A detailed description of the product. | No | "High-fidelity audio with noise cancellation." |
| price | number | The price of the product. | Yes | 129.99 |
| category | string | The category the product belongs to. | Yes | "Electronics" |
| stock | integer | The current stock quantity of the product. Default is 0. | No | 100 |
Request Example (cURL):
curl -X POST \
'https://api.pantherahive.com/v1/products' \
-H 'X-API-Key: YOUR_API_KEY_HERE' \
-H 'Content-Type: application