# Yalla Hack Blog API Documentation

**Version:** 1.0  
**Base URL:** `https://yalla-hack.ae/api`  
**Last Updated:** October 26, 2025

---

## Table of Contents

1. [Overview](#overview)
2. [Authentication](#authentication)
3. [API Endpoints](#api-endpoints)
   - [Blog Webhook (n8n Integration)](#blog-webhook-n8n-integration)
   - [Add Blog](#add-blog)
   - [Get Blogs](#get-blogs)
   - [Get Single Blog](#get-single-blog)
   - [View Submissions](#view-submissions)
4. [Request & Response Format](#request--response-format)
5. [Error Handling](#error-handling)
6. [Rate Limiting](#rate-limiting)
7. [Examples](#examples)
8. [Integration Guides](#integration-guides)
   - [n8n Form Integration](#n8n-form-integration)
9. [Troubleshooting](#troubleshooting)
10. [Support](#support)

---

## Overview

The Yalla Hack Blog API provides a RESTful interface for managing blog posts. It supports creating, reading, and retrieving blog content with full HTML support, author attribution, and reading time estimates.

### Key Features

- ✅ **RESTful Architecture** - Standard HTTP methods (GET, POST)
- ✅ **JSON Responses** - All responses in JSON format
- ✅ **HTML Content Support** - Rich text formatting with full HTML
- ✅ **Security** - Authentication protected, SQL injection prevention
- ✅ **CORS Enabled** - Cross-origin requests supported
- ✅ **UTF-8 Encoding** - Full international character support
- ✅ **Auto-slugification** - Automatic URL-friendly slug generation
- ✅ **Timestamps** - Automatic creation and update timestamps

### Base URL

```
https://yalla-hack.ae/api
```

All API requests should be made to this base URL followed by the endpoint path.

---

## Authentication

### Authentication Method

The API uses **header-based authentication** for protected endpoints.

**Authentication Header:**
```
admin: 11aa22ss
```

### Protected Endpoints

Only the following endpoint requires authentication:
- `POST /add_blog.php` - Create new blog post

### Public Endpoints

These endpoints are publicly accessible without authentication:
- `GET /get_blogs.php` - Retrieve all blog posts
- `GET /get_blog.php` - Retrieve single blog post
- `GET /test.php` - Health check endpoint
- `GET /rss.php` - RSS 2.0 feed of latest blog posts

### Authentication Example

```bash
curl -X POST https://yalla-hack.ae/api/add_blog.php \
  -H "Content-Type: application/json" \
  -H "admin: 11aa22ss" \
  -d '{"title":"Test Post","content":"Content here"}'
```

### Security Notes

⚠️ **Important:**
- Keep the authentication key secure
- Never expose the key in client-side code
- Use HTTPS for all requests
- Rotate the key periodically for security
- Monitor API usage for suspicious activity

---

## API Endpoints
---

### 1. Blog Webhook (n8n Integration)

**NEW!** Public webhook endpoint for n8n form integration. Receives blog submissions from external forms and forwards to the authenticated API.

**Endpoint:** `POST /blog-webhook.php`

**Authentication:** None required (internally forwards with authentication)

**Description:** Accepts blog submissions from n8n forms or external sources. Validates data, logs submissions, and forwards to the authenticated add_blog.php endpoint.

**Content-Type:** 
- `application/json` (Recommended)
- `application/x-www-form-urlencoded` (Form data)

**Request (JSON):**
```http
POST /api/blog-webhook.php
Content-Type: application/json

{
  "title": "Understanding Modern Cybersecurity Threats",
  "content": "<h2>Introduction</h2><p>Cybersecurity is evolving...</p>",
  "author": "John Doe",
  "image_url": "https://example.com/image.jpg",
  "time_read": "7 min read"
}
```

**Request (Form Data):**
```http
POST /api/blog-webhook.php
Content-Type: application/x-www-form-urlencoded

blog_title=Understanding Modern Cybersecurity Threats
blog_content=<h2>Introduction</h2><p>Cybersecurity is evolving...</p>
blog_author=John Doe
image_url=https://example.com/image.jpg
time_read=7 min read
```

**Success Response:**
```json
{
  "success": true,
  "message": "Blog post submitted successfully",
  "id": 42,
  "slug": "understanding-modern-cybersecurity-threats",
  "url": "https://yalla-hack.ae/blog-post.html?slug=understanding-modern-cybersecurity-threats"
}
```

**Error Response:**
```json
{
  "success": false,
  "error": "Missing required fields: title and content"
}
```

**Required Fields:**
- `title` or `blog_title` - Blog post title
- `content` or `blog_content` - Blog content (HTML supported)

**Optional Fields:**
- `author` or `blog_author` - Author name (defaults to "Yalla Hack Team")
- `image_url` - Featured image URL
- `time_read` - Reading time estimate (defaults to "5 min read")

**Features:**
- ✅ Automatic authentication handling
- ✅ Submission logging for tracking
- ✅ Support for both JSON and form data
- ✅ IP and user agent tracking
- ✅ Automatic URL generation

**Use Cases:**
- n8n form submissions
- External blog submission forms
- Automated content publishing
- Third-party integrations

**See Also:** [N8N-BLOG-INTEGRATION.md](./N8N-BLOG-INTEGRATION.md) for complete setup guide

---

### 2. Health Check

Check API availability and database connectivity.

**Endpoint:** `GET /test.php`

**Authentication:** None required (optional)

**Description:** Returns the status of the database connection and authentication.

**Request:**
```http
GET /api/test.php
```

**Response:**
```json
{
  "db": true,
  "auth": false
}
```

**Response with Authentication:**
```bash
curl -H "admin: 11aa22ss" https://yalla-hack.ae/api/test.php
```
```json
{
  "db": true,
  "auth": true
}
```

**Response Fields:**
- `db` (boolean) - Database connection status
- `auth` (boolean) - Authentication status

---

### 2. Get All Blog Posts

Retrieve all blog posts ordered by creation date (newest first).

**Endpoint:** `GET /get_blogs.php`

**Authentication:** None required

**Description:** Returns an array of all blog posts with complete metadata.

**Request:**
```http
GET /api/get_blogs.php
```

**Response:**
```json
[
  {
    "id": "1",
    "title": "Welcome to Yalla Hack Blog",
    "slug": "welcome-to-yalla-hack-blog",
    "content": "Welcome to the official Yalla Hack blog...",
    "image_url": "https://images.unsplash.com/photo-1550751827-4bd374c3f58b?w=800",
    "author": "Yalla Hack Team",
    "time_read": "5 min read",
    "created_at": "2025-10-26 23:27:25"
  },
  {
    "id": "2",
    "title": "Advanced Penetration Testing",
    "slug": "advanced-penetration-testing",
    "content": "Learn advanced pentesting techniques...",
    "image_url": "https://example.com/image2.jpg",
    "author": "Mohammed Ahmed",
    "time_read": "12 min read",
    "created_at": "2025-10-27 10:15:30"
  }
]
```

**Response Fields:**
- `id` (string) - Unique blog post identifier
- `title` (string) - Blog post title
- `slug` (string) - URL-friendly identifier
- `content` (string) - Full blog content (HTML or plain text)
- `image_url` (string|null) - Featured image URL
- `author` (string) - Author name
- `time_read` (string) - Estimated reading time
- `created_at` (string) - Creation timestamp (YYYY-MM-DD HH:MM:SS)

**Empty Response:**
```json
[]
```

---

### 3. Get Single Blog Post

Retrieve a specific blog post by its slug.

**Endpoint:** `GET /get_blog.php?slug={slug}`

**Authentication:** None required

**Description:** Returns a single blog post matching the provided slug.

**Parameters:**
- `slug` (required, string) - The URL-friendly identifier of the blog post

**Request:**
```http
GET /api/get_blog.php?slug=welcome-to-yalla-hack-blog
```

**Response (Success):**
```json
{
  "id": 1,
  "title": "Welcome to Yalla Hack Blog",
  "slug": "welcome-to-yalla-hack-blog",
  "content": "Welcome to the official Yalla Hack blog...",
  "image_url": "https://images.unsplash.com/photo-1550751827-4bd374c3f58b?w=800",
  "author": "Yalla Hack Team",
  "time_read": "5 min read",
  "created_at": "2025-10-26 23:27:25"
}
```

**Response (Not Found):**
```json
{
  "error": "Not found"
}
```
HTTP Status: `404`

**Error Response (Missing Slug):**
```json
{
  "error": "Missing slug"
}
```

---

### 5. View Blog Submissions

**NEW!** View and track blog submissions from the n8n webhook. Protected endpoint for monitoring form submissions.

**Endpoint:** `GET /view-submissions.php`

**Authentication:** Required (`admin: 11aa22ss`)

**Description:** Returns logged blog submissions with statistics and filtering options.

**Headers:**
```
admin: 11aa22ss
```

**Query Parameters:**
- `status` (optional) - Filter by status: `success`, `error`, `api_error`, `exception`
- `limit` (optional) - Maximum number of results (default: 50)
- `search` (optional) - Search by title or author

**Request Examples:**
```http
# Get all submissions
GET /api/view-submissions.php

# Get only successful submissions
GET /api/view-submissions.php?status=success

# Get only errors
GET /api/view-submissions.php?status=error

# Search for specific blog
GET /api/view-submissions.php?search=cybersecurity

# Limit results
GET /api/view-submissions.php?limit=10
```

**Response:**
```json
{
  "success": true,
  "count": 15,
  "total_submissions": 23,
  "statistics": {
    "success": 20,
    "errors": 3,
    "success_rate": 86.96
  },
  "submissions": [
    {
      "timestamp": "2026-01-05 14:30:00",
      "ip": "192.168.1.1",
      "user_agent": "n8n-webhook/1.0",
      "input_type": "json",
      "blog_title": "Understanding Modern Threats",
      "blog_author": "John Doe",
      "status": "success",
      "blog_id": 42,
      "blog_slug": "understanding-modern-threats"
    },
    {
      "timestamp": "2026-01-05 13:15:00",
      "ip": "192.168.1.2",
      "user_agent": "PostmanRuntime/7.26.8",
      "input_type": "json",
      "blog_title": "Test Blog",
      "blog_author": "Test User",
      "status": "error",
      "error": "Missing required fields: content"
    }
  ]
}
```

**Response Fields:**
- `success` (boolean) - Request status
- `count` (number) - Number of submissions returned
- `total_submissions` (number) - Total submissions in log
- `statistics` (object) - Submission statistics
  - `success` (number) - Successful submissions
  - `errors` (number) - Failed submissions
  - `success_rate` (number) - Percentage of successful submissions
- `submissions` (array) - List of submission records

**Submission Record Fields:**
- `timestamp` - Submission date/time
- `ip` - Client IP address
- `user_agent` - Client user agent
- `input_type` - Input format (`json` or `form`)
- `blog_title` - Submitted blog title
- `blog_author` - Submitted author name
- `status` - Submission status
- `blog_id` - Created blog ID (success only)
- `blog_slug` - Generated slug (success only)
- `error` - Error message (errors only)

**Use Cases:**
- Monitor form submissions
- Track success rates
- Debug integration issues
- Audit blog creation
- Generate reports

---

### 6. RSS Feed

Create a new blog post with optional HTML content.

**Endpoint:** `POST /add_blog.php`

**Authentication:** Required (`admin: 11aa22ss`)

**Description:** Creates a new blog post and automatically generates a URL-friendly slug.

**Headers:**
```
Content-Type: application/json
admin: 11aa22ss
```

---

### 7. Create Blog Post

Create a new blog post with optional HTML content.

**Endpoint:** `POST /add_blog.php`

**Authentication:** Required (`admin: 11aa22ss`)

**Description:** Creates a new blog post and automatically generates a URL-friendly slug. This is the internal API - for public submissions use `/blog-webhook.php` instead.

**Headers:**
```
Content-Type: application/json
admin: 11aa22ss
```

**Request Body:**
```json
{
  "title": "Blog Post Title",
  "content": "Blog post content (HTML or plain text)",
  "image_url": "https://example.com/image.jpg",
  "author": "Author Name",
  "time_read": "10 min read"
}
```

**Request Fields:**

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `title` | string | ✅ Yes | - | Blog post title (max 255 chars) |
| `content` | string | ✅ Yes | - | Blog content (supports HTML) |
| `image_url` | string | ❌ No | `null` | Featured image URL (max 500 chars) |
| `author` | string | ❌ No | `"Yalla Hack Team"` | Author name (max 255 chars) |
| `time_read` | string | ❌ No | `"5 min read"` | Reading time estimate (max 50 chars) |

**Complete Request Example:**
```bash
curl -X POST https://yalla-hack.ae/api/add_blog.php \
  -H "Content-Type: application/json" \
  -H "admin: 11aa22ss" \
  -d '{
    "title": "Advanced Penetration Testing Techniques",
    "content": "<h2>Introduction</h2><p>Learn advanced pentesting...</p>",
    "image_url": "https://images.unsplash.com/photo-1550751827-4bd374c3f58b?w=800",
    "author": "Mohammed Ahmed",
    "time_read": "12 min read"
  }'
```

**Minimal Request Example:**
```bash
curl -X POST https://yalla-hack.ae/api/add_blog.php \
  -H "Content-Type: application/json" \
  -H "admin: 11aa22ss" \
  -d '{
    "title": "Quick Security Tip",
    "content": "Always use strong passwords!"
  }'
```

**Response (Success):**
```json
{
  "success": true,
  "id": 3,
  "slug": "advanced-penetration-testing-techniques"
}
```
HTTP Status: `200`

**Response Fields:**
- `success` (boolean) - Operation status
- `id` (integer) - ID of the newly created blog post
- `slug` (string) - Auto-generated URL-friendly slug

---

### 5. RSS Feed (Public)

Consume the 20 most recent blog posts in RSS 2.0 format for syndication platforms.

**Endpoint:** `GET /rss.php`

**Authentication:** None required

**Description:** Returns an XML feed containing metadata for the latest published blog posts. Ideal for newsletter automation, LinkedIn content ingestion, and RSS readers.

**Headers:**
```
Content-Type: application/rss+xml; charset=UTF-8
```

**Request:**
```http
GET /rss.php
```

**Response (Truncated):**
```xml
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
  <channel>
    <title>Yalla-Hack Cybersecurity Blog</title>
    <link>https://yalla-hack.com/</link>
    <description>Latest cybersecurity insights, threat intelligence, and best practices from the Yalla-Hack team.</description>
    <lastBuildDate>Mon, 03 Nov 2025 09:00:00 +0000</lastBuildDate>
    <item>
      <title>Welcome to Yalla Hack Blog</title>
      <link>https://yalla-hack.com/blog-post.html?slug=welcome-to-yalla-hack-blog</link>
      <guid isPermaLink="true">https://yalla-hack.com/blog-post.html?slug=welcome-to-yalla-hack-blog</guid>
      <description>Welcome to the official Yalla Hack blog...</description>
      <pubDate>Mon, 03 Nov 2025 08:30:00 +0000</pubDate>
    </item>
    <!-- More items (maximum 20) -->
  </channel>
</rss>
```

**Notes:**
- Feed is cached for five minutes to reduce database load.
- All XML characters are escaped to remain validator-friendly.
- Only published posts with timestamps are included.
- `pubDate` is formatted using RFC 822 (`DATE_RSS`).

---

## Request & Response Format

### Content Type

All API responses use JSON format unless noted otherwise. The RSS feed (`/rss.php`) delivers XML syndication data.
```
Content-Type: application/json
```
```
Content-Type: application/rss+xml; charset=UTF-8
```

### Character Encoding

All data is encoded in UTF-8:
```
Charset: UTF-8
```

### Slug Generation

Slugs are automatically generated from the title:

**Rules:**
1. Convert to lowercase
2. Replace spaces with hyphens
3. Remove special characters
4. Trim leading/trailing hyphens

**Examples:**
- `"Hello World"` → `"hello-world"`
- `"Top 10 Security Tips!"` → `"top-10-security-tips"`
- `"What is XSS?"` → `"what-is-xss"`

If the title results in an empty slug, a unique identifier is generated: `post-{uniqid}`

### Date Format

All timestamps use MySQL datetime format:
```
YYYY-MM-DD HH:MM:SS
Example: 2025-10-26 23:27:25
```

### Boolean Values

Booleans are represented as:
- `true` (JSON boolean)
- `false` (JSON boolean)

### Null Values

Null values are represented as:
- `null` (JSON null)

---

## Error Handling

### HTTP Status Codes

| Status Code | Meaning | Description |
|------------|---------|-------------|
| `200` | OK | Request succeeded |
| `400` | Bad Request | Invalid request format or missing required fields |
| `401` | Unauthorized | Missing or invalid authentication |
| `404` | Not Found | Resource not found |
| `405` | Method Not Allowed | Invalid HTTP method |
| `500` | Internal Server Error | Server or database error |

### Error Response Format

All errors return a JSON object with an `error` field:

```json
{
  "error": "Error message description"
}
```

### Common Errors

#### 1. Unauthorized (401)

**Cause:** Missing or incorrect authentication header

**Request:**
```bash
curl -X POST https://yalla-hack.ae/api/add_blog.php \
  -H "Content-Type: application/json" \
  -d '{"title":"Test","content":"Test"}'
```

**Response:**
```json
{
  "error": "Unauthorized"
}
```

**Solution:** Add the authentication header: `admin: 11aa22ss`

---

#### 2. Missing Required Fields (400)

**Cause:** Missing `title` or `content` in request body

**Request:**
```bash
curl -X POST https://yalla-hack.ae/api/add_blog.php \
  -H "Content-Type: application/json" \
  -H "admin: 11aa22ss" \
  -d '{"title":"Test"}'
```

**Response:**
```json
{
  "error": "Missing required fields: title and content"
}
```

**Solution:** Include both `title` and `content` in request body

---

#### 3. Method Not Allowed (405)

**Cause:** Using wrong HTTP method

**Request:**
```bash
curl -X GET https://yalla-hack.ae/api/add_blog.php
```

**Response:**
```json
{
  "error": "Only POST allowed"
}
```

**Solution:** Use correct HTTP method (POST for `add_blog.php`)

---

#### 4. Not Found (404)

**Cause:** Blog post with specified slug doesn't exist

**Request:**
```bash
curl https://yalla-hack.ae/api/get_blog.php?slug=non-existent-post
```

**Response:**
```json
{
  "error": "Not found"
}
```

**Solution:** Verify the slug is correct

---

#### 5. Database Connection Failed (500)

**Cause:** Cannot connect to database

**Response:**
```json
{
  "error": "Database connection failed"
}
```

**Solution:** Contact system administrator

---

## Rate Limiting

### Current Status

⚠️ **No rate limiting currently implemented**

The API does not currently enforce rate limits. However, please use the API responsibly:

- Avoid excessive requests
- Implement client-side caching
- Use appropriate delays between requests
- Don't perform bulk operations without planning

### Best Practices

**Recommended:**
- Cache `get_blogs.php` responses for 5-10 minutes
- Implement exponential backoff for failed requests
- Don't poll the API continuously
- Batch operations when possible

---

## Examples

### Example 1: Creating a Simple Blog Post

**Scenario:** Create a basic blog post with minimal fields

```bash
curl -X POST https://yalla-hack.ae/api/add_blog.php \
  -H "Content-Type: application/json" \
  -H "admin: 11aa22ss" \
  -d '{
    "title": "5 Essential Security Tips",
    "content": "Here are 5 essential security tips every organization should follow:\n\n1. Use strong passwords\n2. Enable 2FA\n3. Keep software updated\n4. Regular backups\n5. Security training"
  }'
```

**Response:**
```json
{
  "success": true,
  "id": 10,
  "slug": "5-essential-security-tips"
}
```

---

### Example 2: Creating a Blog Post with HTML

**Scenario:** Create a rich blog post with HTML formatting

```bash
curl -X POST https://yalla-hack.ae/api/add_blog.php \
  -H "Content-Type: application/json" \
  -H "admin: 11aa22ss" \
  -d '{
    "title": "Understanding Zero-Day Vulnerabilities",
    "content": "<h2 class=\"text-3xl font-bold text-white mb-4\">What is a Zero-Day?</h2><p class=\"text-gray-300 text-lg mb-6\">A zero-day vulnerability is a security flaw that is unknown to the software vendor...</p><ul class=\"list-disc ml-6 text-gray-300 mb-6\"><li>Immediate threat</li><li>No patch available</li><li>High-value targets</li></ul>",
    "image_url": "https://images.unsplash.com/photo-1555949963-ff9fe0c870eb?w=800",
    "author": "Dr. Sarah Ahmed",
    "time_read": "15 min read"
  }'
```

**Response:**
```json
{
  "success": true,
  "id": 11,
  "slug": "understanding-zero-day-vulnerabilities"
}
```

---

### Example 3: Retrieving All Posts

**Scenario:** Get all blog posts for display on blog listing page

```bash
curl https://yalla-hack.ae/api/get_blogs.php
```

**Response:**
```json
[
  {
    "id": "11",
    "title": "Understanding Zero-Day Vulnerabilities",
    "slug": "understanding-zero-day-vulnerabilities",
    "content": "<h2>What is a Zero-Day?</h2>...",
    "image_url": "https://images.unsplash.com/photo-1555949963-ff9fe0c870eb?w=800",
    "author": "Dr. Sarah Ahmed",
    "time_read": "15 min read",
    "created_at": "2025-10-27 14:30:00"
  },
  {
    "id": "10",
    "title": "5 Essential Security Tips",
    "slug": "5-essential-security-tips",
    "content": "Here are 5 essential security tips...",
    "image_url": null,
    "author": "Yalla Hack Team",
    "time_read": "5 min read",
    "created_at": "2025-10-27 12:15:00"
  }
]
```

---

### Example 4: Retrieving a Specific Post

**Scenario:** Get a single blog post for display on individual post page

```bash
curl "https://yalla-hack.ae/api/get_blog.php?slug=5-essential-security-tips"
```

**Response:**
```json
{
  "id": 10,
  "title": "5 Essential Security Tips",
  "slug": "5-essential-security-tips",
  "content": "Here are 5 essential security tips...",
  "image_url": null,
  "author": "Yalla Hack Team",
  "time_read": "5 min read",
  "created_at": "2025-10-27 12:15:00"
}
```

---

## Integration Guides

### JavaScript/Fetch API

```javascript
// Get all blog posts
async function getAllBlogs() {
  try {
    const response = await fetch('https://yalla-hack.ae/api/get_blogs.php');
    
    if (!response.ok) {
      throw new Error('Failed to fetch blogs');
    }
    
    const blogs = await response.json();
    return blogs;
  } catch (error) {
    console.error('Error fetching blogs:', error);
    return [];
  }
}

// Create a new blog post
async function createBlog(blogData) {
  try {
    const response = await fetch('https://yalla-hack.ae/api/add_blog.php', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'admin': '11aa22ss'
      },
      body: JSON.stringify(blogData)
    });
    
    if (!response.ok) {
      throw new Error('Failed to create blog post');
    }
    
    const result = await response.json();
    console.log('Blog created:', result);
    return result;
  } catch (error) {
    console.error('Error creating blog:', error);
    return null;
  }
}

// Usage
getAllBlogs().then(blogs => {
  console.log('All blogs:', blogs);
});

createBlog({
  title: 'My Blog Post',
  content: 'Blog content here',
  author: 'John Doe',
  time_read: '5 min read'
});
```

---

### Python/Requests

```python
import requests
import json

# Base URL
BASE_URL = 'https://yalla-hack.ae/api'

# Get all blog posts
def get_all_blogs():
    try:
        response = requests.get(f'{BASE_URL}/get_blogs.php')
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f'Error: {e}')
        return []

# Create a new blog post
def create_blog(blog_data):
    headers = {
        'Content-Type': 'application/json',
        'admin': '11aa22ss'
    }
    
    try:
        response = requests.post(
            f'{BASE_URL}/add_blog.php',
            headers=headers,
            json=blog_data
        )
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f'Error: {e}')
        return None

# Usage
blogs = get_all_blogs()
print(f'Found {len(blogs)} blog posts')

result = create_blog({
    'title': 'My Python Blog Post',
    'content': 'Content created from Python',
    'author': 'Python Script',
    'time_read': '3 min read'
})
print('Created:', result)
```

---

### PHP/cURL

```php
<?php

// Get all blog posts
function getAllBlogs() {
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, 'https://yalla-hack.ae/api/get_blogs.php');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Create a new blog post
function createBlog($blogData) {
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, 'https://yalla-hack.ae/api/add_blog.php');
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($blogData));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'admin: 11aa22ss'
    ]);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Usage
$blogs = getAllBlogs();
echo "Found " . count($blogs) . " blog posts\n";

$result = createBlog([
    'title' => 'My PHP Blog Post',
    'content' => 'Content created from PHP',
    'author' => 'PHP Script',
    'time_read' => '4 min read'
]);
print_r($result);
```

---

### n8n Workflow

**HTTP Request Node Configuration:**

**Method:** POST  
**URL:** `https://yalla-hack.ae/api/add_blog.php`

**Headers:**
```
Content-Type: application/json
admin: 11aa22ss
```

**Body (JSON):**
```json
{
  "title": "{{ $json.title }}",
  "content": "{{ $json.content }}",
  "image_url": "{{ $json.image_url }}",
  "author": "{{ $json.author }}",
  "time_read": "{{ $json.time_read }}"
}
```

---

### Postman Collection

**Create Blog Post Request:**

1. **Method:** POST
2. **URL:** `https://yalla-hack.ae/api/add_blog.php`
3. **Headers:**
   - `Content-Type`: `application/json`
   - `admin`: `11aa22ss`
4. **Body (raw JSON):**
```json
{
  "title": "Test from Postman",
  "content": "This is a test blog post",
  "author": "Postman User",
  "time_read": "2 min read"
}
```

---

## Troubleshooting

### Common Issues

#### Issue 1: CORS Error in Browser

**Error:**
```
Access to fetch at 'https://yalla-hack.ae/api/...' from origin 'http://localhost' 
has been blocked by CORS policy
```

**Solution:**
The API has `Access-Control-Allow-Origin: *` enabled. This usually happens in local development. Deploy to production or use a proxy.

---

#### Issue 2: 401 Unauthorized

**Error:**
```json
{"error": "Unauthorized"}
```

**Checklist:**
- ✅ Are you including the `admin` header?
- ✅ Is the header value exactly `11aa22ss`?
- ✅ Is the header name exactly `admin` (lowercase)?
- ✅ Are you using the correct endpoint (`add_blog.php`)?

---

#### Issue 3: Empty Response

**Error:** Empty `[]` array from `get_blogs.php`

**Possible Causes:**
1. No blog posts in database yet
2. Database connection issue

**Solution:**
1. Check `/api/test.php` to verify database connection
2. Create your first blog post using `add_blog.php`

---

#### Issue 4: HTML Not Rendering

**Problem:** HTML content displays as plain text

**Solution:** This is a frontend issue, not API. The API correctly stores and returns HTML. Ensure your frontend uses `innerHTML` not `textContent`.

**Correct:**
```javascript
element.innerHTML = blog.content;
```

**Incorrect:**
```javascript
element.textContent = blog.content; // Will show HTML tags
```

---

#### Issue 5: Special Characters Broken

**Problem:** Special characters (é, ñ, ø, etc.) display incorrectly

**Solution:**
- Ensure your request uses UTF-8 encoding
- Set `Content-Type: application/json; charset=utf-8`
- Database is already configured for UTF-8

---

## Database Schema

For reference, here's the complete database structure:

```sql
CREATE TABLE blogs (
    id INT AUTO_INCREMENT PRIMARY KEY,
    title VARCHAR(255) NOT NULL,
    slug VARCHAR(255) UNIQUE NOT NULL,
    content TEXT NOT NULL,
    image_url VARCHAR(500),
    author VARCHAR(255) DEFAULT 'Yalla Hack Team',
    time_read VARCHAR(50) DEFAULT '5 min read',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_slug (slug),
    INDEX idx_created (created_at),
    INDEX idx_author (author)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```

**Indexes:**
- Primary key on `id`
- Unique index on `slug`
- Index on `created_at` (for ordering)
- Index on `author` (for filtering)

---

## Best Practices

### 1. Content Creation

✅ **DO:**
- Use descriptive, SEO-friendly titles
- Include featured images when available
- Calculate accurate reading times
- Format HTML content properly
- Attribute content to appropriate authors

❌ **DON'T:**
- Use very long titles (>255 chars)
- Include JavaScript in content
- Use external stylesheets in HTML
- Create duplicate slugs manually

---

### 2. Error Handling

✅ **DO:**
- Always check HTTP status codes
- Handle errors gracefully in your application
- Log errors for debugging
- Provide user-friendly error messages
- Implement retry logic for transient errors

❌ **DON'T:**
- Ignore error responses
- Expose raw error messages to users
- Retry indefinitely without backoff

---

### 3. Performance

✅ **DO:**
- Cache blog listings for 5-10 minutes
- Paginate when displaying many posts
- Use CDN for images
- Implement lazy loading for images
- Compress images before uploading

❌ **DON'T:**
- Fetch all blogs on every page load
- Store images in the database
- Make unnecessary API calls

---

### 4. Security

✅ **DO:**
- Always use HTTPS
- Keep authentication keys secure
- Validate and sanitize user input
- Monitor API usage
- Rotate authentication keys regularly

❌ **DON'T:**
- Hardcode auth keys in client-side code
- Share authentication keys publicly
- Allow SQL injection vulnerabilities
- Disable HTTPS for "convenience"

---

## API Changelog

### Version 1.0 (October 26, 2025)

**Added:**
- ✅ `GET /get_blogs.php` - Retrieve all blog posts
- ✅ `GET /get_blog.php` - Retrieve single blog post
- ✅ `POST /add_blog.php` - Create new blog post
- ✅ `GET /test.php` - Health check endpoint
- ✅ Authentication via header
- ✅ HTML content support
- ✅ Author attribution
- ✅ Reading time estimates
- ✅ Automatic slug generation
- ✅ UTF-8 support
- ✅ CORS enabled

---

## Support

### Contact Information

**Email:** Support@yalla-hack.net  
**Phone:** +8618326095404  
**Website:** https://yalla-hack.ae

### Reporting Issues

When reporting API issues, please include:
1. Endpoint being accessed
2. Request headers and body
3. Response received
4. Expected behavior
5. Steps to reproduce

### Getting Help

For API support:
- Email technical questions to Support@yalla-hack.net
- Include "API Support" in the subject line
- Provide request/response examples
- Include error messages if applicable

---

## License & Usage

### Terms of Use

This API is provided for use with the Yalla Hack website and authorized applications.

**You may:**
- ✅ Use the API for your authorized applications
- ✅ Create blog posts with proper attribution
- ✅ Cache responses for performance
- ✅ Integrate with automation tools (n8n, Zapier, etc.)

**You may not:**
- ❌ Abuse the API with excessive requests
- ❌ Attempt to bypass authentication
- ❌ Use the API for malicious purposes
- ❌ Share authentication credentials
- ❌ Resell or redistribute API access

---

## Appendix

### A. HTTP Status Code Reference

| Code | Name | Description |
|------|------|-------------|
| 200 | OK | Successful request |
| 400 | Bad Request | Invalid request format |
| 401 | Unauthorized | Authentication required/invalid |
| 404 | Not Found | Resource doesn't exist |
| 405 | Method Not Allowed | Wrong HTTP method |
| 500 | Internal Server Error | Server error |

### B. Content-Type Reference

| Type | Usage |
|------|-------|
| `application/json` | All API requests/responses |
| `text/html` | HTML content in blog posts |

### C. Authentication Header Reference

| Header | Value | Required For |
|--------|-------|--------------|
| `admin` | `11aa22ss` | POST /add_blog.php |
| `Content-Type` | `application/json` | All POST requests |

---

**END OF DOCUMENTATION**

*Last Updated: October 26, 2025*  
*Version: 1.0*  
*© 2025 Yalla Hack. All rights reserved.*