RESTful API

Headless CMS & RESTful API Engine

---

GeniXCMS 2.0.0 features a powerful, built-in RESTful API Engine that allows you to use the platform as a Headless CMS. This architecture enables you to decouple your content management from your frontend delivery, serving your data to mobile apps, static site generators (like Hugo or Gatsby), or custom JavaScript frameworks.

---

🔐 Administrative Authentication

To interact with the API, requests must be authenticated using a valid GX-API-KEY. The system supports two primary delivery methods:

1. Request Header (Recommended):
   • Key: GX-API-KEY
   • Value: your_secret_api_key_here
2. Query String (Development only):
   • URL suffix: ?api-key=your_secret_api_key_here

---

🧭 Global Endpoint Structure

The GeniXCMS API follows standard RESTful naming conventions.

• Base URL: https://yourdomain.com/api/v1/
• Pattern: /{resource}/{identifier}

---

🏹 Standard Content Resources (Posts)

The posts resource is the primary interface for managing editorial content via the API.

Capability	HTTP Method	Endpoint Path
List Records	GET	/api/v1/posts/
Fetch Single	GET	/api/v1/posts/{id}
Create New	POST	/api/v1/posts/
Update Existing	PUT	/api/v1/posts/{id}
Permanent Delete	DELETE	/api/v1/posts/{id}

JSON Payload Example (POST/PUT)

{
    "title": "Post from Mobile App",
    "content": "<h1>Hello API</h1><p>Content body goes here...</p>",
    "status": "1",
    "type": "post",
    "author": "clark_kent"
}

---

📦 Consistent Response Architecture

The API engine returns predictable JSON structures for both success and error states.

Success Envelope (200 OK)

{
    "status": "success",
    "message": "Resource retrieved successfully",
    "records": 42,
    "data": [ { ... }, { ... } ]
}

Error Envelope (4xx / 5xx)

{
    "status": "error",
    "code": 404,
    "message": "The requested resource 'member/12' does not exist."
}

---

🚦 Rate Limiting & Quotas

To ensure platform stability and protect against brute-force attacks, the GeniXCMS API implements a Sliding Window Rate Limiter.

Default Quotas

By default, the system tracks requests per IP address over a 1-hour window.

• Global Limit: Configurable via api_rate_limit (Default: 100 requests/hour).
• Exceeded State: If a client exceeds the quota, the API returns a 429 Too Many Requests status code.

HTTP Response Headers

Clients should monitor these headers to stay within their allocated budget:

Header	Description
X-RateLimit-Limit	The maximum number of requests allowed in the current window.
X-RateLimit-Remaining	The number of requests remaining for the current IP.
X-RateLimit-Reset	The UTC timestamp (Unix) when the current window resets.

---

🛠️ Extensibility: Creating Custom Endpoints

Developers can easily register new API resources by creating a specialized controller class.

• Storage Location: inc/lib/Control/Api/
• Naming Convention: [Resource]Api.class.php
• Routing: The Api Class automatically detects and routes the {resource} segment of the URL to your custom class.

---

---

---

---

⚙️ Configuring the Rate Limiter

Rate limiting is fully configurable from the Admin Dashboard — no code changes required.

Location: Admin > Settings > Security > RESTful API KEY

Field	Description
Rate Limit (Req/Hour)	Maximum number of requests allowed per IP per hour.
Value: 0	Disables rate limiting entirely (open access).
Value: 100	Default — allows 100 requests per IP per hour.

429 Error Response

When a client exceeds their quota, the API returns:

{
    "status": "error",
    "code": 429,
    "message": "Too many requests [Rate Limit Exceeded]"
}

---

---

See Also

• Security Settings — Configuring API keys and CORS policies.
• Posts Class — The underlying model consumed by the Posts API.