API Reference

GET /api/v1/posts HTTP/1.1
Host: blogware.site
X-API-Key: your-api-key-here

GET /api/v1/posts HTTP/1.1
Host: blogware.site
Authorization: Bearer your-bearer-token

{
  "success": true,
  "status": 200,
  "message": "Welcome to Blogware RESTful API",
  "data": {
    "name": "Blogware RESTful API",
    "version": "1.1.2",
    "description": "RESTful API for Blogware content management system",
    "base_url": "/api/v1",
    "authentication": {
      "type": "API Key or Bearer Token",
      "header": "X-API-Key or Authorization: Bearer <token>",
      "required": false
    }
  },
  "_links": {
    "self": { "href": "http://blogware.site/api/v1", "rel": "self", "type": "GET" },
    "posts": { "href": "http://blogware.site/api/v1/posts", "rel": "posts", "type": "GET" },
    "categories": { "href": "http://blogware.site/api/v1/categories", "rel": "categories", "type": "GET" },
    "comments": { "href": "http://blogware.site/api/v1/comments", "rel": "comments", "type": "GET" },
    "archives": { "href": "http://blogware.site/api/v1/archives", "rel": "archives", "type": "GET" },
    "search": { "href": "http://blogware.site/api/v1/search?q={query}", "rel": "search", "type": "GET", "templated": true },
    "gdpr": { "href": "http://blogware.site/api/v1/gdpr/consent", "rel": "gdpr", "type": "GET" },
    "languages": { "href": "http://blogware.site/api/v1/languages", "rel": "languages", "type": "GET" },
    "translations": { "href": "http://blogware.site/api/v1/translations/en", "rel": "translations", "type": "GET" },
    "media": { "href": "http://blogware.site/api/v1/media/upload", "rel": "media", "type": "POST" },
    "openapi": { "href": "http://blogware.site/api/v1/openapi.json", "rel": "service-desc", "type": "application/json" }
  }
}

{
  "success": true,
  "status": 200,
  "data": [...],
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total_items": 50,
    "total_pages": 5,
    "has_next_page": true,
    "has_previous_page": false
  },
  "_links": {
    "self": { "href": "http://blogware.site/api/v1/posts?page=1", "rel": "self", "type": "GET" },
    "next": { "href": "http://blogware.site/api/v1/posts?page=2", "rel": "next", "type": "GET" },
    "last": { "href": "http://blogware.site/api/v1/posts?page=5", "rel": "last", "type": "GET" }
  }
}

{
  "post_title": "My New Post",
  "post_content": "Full content of the post",
  "post_summary": "Optional summary",
  "post_status": "draft",
  "post_visibility": "public",
  "post_tags": "php, api",
  "comment_status": "open",
  "topics": [1, 2]
}

{
  "success": true,
  "status": 200,
  "data": [
    {
      "id": 1,
      "title": "Technology",
      "slug": "technology",
      "status": "Y",
      "post_count": 15,
      "url": "http://blogware.site/category/technology",
      "_links": {
        "self": { "href": "http://blogware.site/api/v1/categories/1", "rel": "self", "type": "GET" },
        "posts": { "href": "http://blogware.site/api/v1/categories/1/posts", "rel": "posts", "type": "GET" },
        "canonical": { "href": "http://blogware.site/category/technology", "rel": "canonical", "type": "text/html" },
        "collection": { "href": "http://blogware.site/api/v1/categories", "rel": "collection", "type": "GET" }
      }
    }
  ],
  "pagination": {...},
  "_links": { ... }
}

{
  "topic_title": "Category Name",
  "topic_status": "Y"
}

{
  "comment_author_name": "John Doe",
  "comment_author_email": "[email protected]",
  "comment_content": "Great article!",
  "comment_post_id": 1,
  "comment_parent_id": 0
}

{
  "success": true,
  "status": 200,
  "data": {
    "archives": [
      {
        "year": 2024,
        "months": [
          {
            "month": 6,
            "month_name": "June",
            "post_count": 5
          }
        ],
        "total_posts": 25
      }
    ],
    "total_years": 3
  },
  "_links": {
    "self": { "href": "http://blogware.site/api/v1", "rel": "self", "type": "GET" },
    "posts": { "href": "http://blogware.site/api/v1/posts", "rel": "posts", "type": "GET" },
    "archives": { "href": "http://blogware.site/api/v1/archives", "rel": "archives", "type": "GET" },
    "search": { "href": "http://blogware.site/api/v1/search?q={query}", "rel": "search", "type": "GET", "templated": true },
    "openapi": { "href": "http://blogware.site/api/v1/openapi.json", "rel": "service-desc", "type": "application/json" }
  }
}

GET /api/v1/search?q=cicero&type=all

{
  "password": "post-password"
}

{
  "lang_code": "de",
  "lang_name": "German",
  "lang_native": "Deutsch",
  "lang_locale": "de_DE",
  "lang_direction": "ltr",
  "lang_is_default": false
}

{
  "lang_code": "en",
  "translation_key": "nav.dashboard",
  "translation_value": "Dashboard",
  "translation_context": "frontend",
  "is_html": false
}

{
  "nav.dashboard": "Dashboard",
  "nav.posts": "Posts",
  "nav.settings": "Settings"
}

{
  "status": "accepted"
}

{
  "success": true,
  "status": 200,
  "message": "API is operational",
  "data": {
    "status": "healthy",
    "timestamp": "2026-07-30 12:00:00",
    "php_version": "8.1.28"
  }
}

{
  "type": "all",
  "q": "search keyword"
}

{
  "success": true,
  "status": 200,
  "message": "Operation description",
  "data": { ... }
}

{
  "success": true,
  "status": 201,
  "message": "Resource created",
  "data": {
    "id": 42
  }
}

{
  "success": true,
  "status": 200,
  "data": [...],
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total_items": 50,
    "total_pages": 5,
    "has_next_page": true,
    "has_previous_page": false
  },
  "_links": {
    "self": { "href": "http://blogware.site/api/v1/posts?page=1", "rel": "self", "type": "GET" },
    "first": { "href": "http://blogware.site/api/v1/posts?page=1", "rel": "first", "type": "GET" },
    "next": { "href": "http://blogware.site/api/v1/posts?page=2", "rel": "next", "type": "GET" },
    "last": { "href": "http://blogware.site/api/v1/posts?page=5", "rel": "last", "type": "GET" }
  }
}

{
  "success": false,
  "status": 400,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Error description"
  }
}

{
  "success": true,
  "status": 200,
  "data": {
    "id": 1,
    "title": "My First Blog Post",
    "slug": "my-first-blog-post"
  },
  "_links": {
    "self": { "href": "http://blogware.site/api/v1/posts/1", "rel": "self", "type": "GET" },
    "comments": { "href": "http://blogware.site/api/v1/posts/1/comments", "rel": "comments", "type": "GET" },
    "canonical": { "href": "http://blogware.site/post/1/my-first-blog-post", "rel": "canonical", "type": "text/html" },
    "collection": { "href": "http://blogware.site/api/v1/posts", "rel": "collection", "type": "GET" }
  }
}

const baseUrl = 'http://blogware.site/api/v1';

// Get posts
const response = await fetch(`${baseUrl}/posts`);
const data = await response.json();

// Get single post
const post = await fetch(`${baseUrl}/posts/1`);

// Create comment (no auth required)
const comment = await fetch(`${baseUrl}/comments`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    comment_author_name: 'John Doe',
    comment_author_email: '[email protected]',
    comment_content: 'Great article!',
    comment_post_id: 1
  })
});

$baseUrl = 'http://blogware.site/api/v1';

// Get posts
$response = file_get_contents($baseUrl . '/posts');
$posts = json_decode($response, true);

// Get posts with authentication
$context = stream_context_create([
  'http' => [
    'header' => "X-API-Key: your-api-key\r\n"
  ]
]);
$response = file_get_contents($baseUrl . '/posts', false, $context);

import requests

base_url = 'http://blogware.site/api/v1'

# Get posts
response = requests.get(f'{base_url}/posts')
posts = response.json()

# Get posts with authentication
headers = {'X-API-Key': 'your-api-key'}
response = requests.get(f'{base_url}/posts', headers=headers)

# Create comment
data = {
    'comment_author_name': 'John Doe',
    'comment_author_email': '[email protected]',
    'comment_content': 'Great article!',
    'comment_post_id': 1
}
response = requests.post(f'{base_url}/comments', json=data)

# Get posts
curl http://blogware.site/api/v1/posts

# Get posts with authentication
curl -H "X-API-Key: your-api-key" http://blogware.site/api/v1/posts

# Create comment
curl -X POST http://blogware.site/api/v1/comments \
  -H "Content-Type: application/json" \
  -d '{
    "comment_author_name": "John Doe",
    "comment_author_email": "[email protected]",
    "comment_content": "Great article!",
    "comment_post_id": 1
  }'

<?php
namespace Scriptlog\Dto\Api;

use Scriptlog\Core\ApiHateoas;

class MyResourceApiDto
{
    public static function transform(array $resource, string $appUrl, ApiHateoas $hateoas): array
    {
        return [
            'id' => (int)$resource['id'],
            'title' => $resource['title'],
            'slug' => $resource['slug'],
            'url' => $appUrl . '/resource/' . $resource['id'] . '/' . $resource['slug'],
            'date' => $resource['created_at'],
            '_links' => $hateoas->rootLinks()
        ];
    }

    public static function transformCollection(array $resources, string $appUrl, ApiHateoas $hateoas): array
    {
        return array_map(function ($r) use ($appUrl, $hateoas) {
            return self::transform($r, $appUrl, $hateoas);
        }, $resources);
    }
}

<?php
namespace Scriptlog\Dao;

class MyResourceDao
{
    private $db;

    public function __construct($db)
    {
        $this->db = $db;
    }

    public function findAll(int $perPage, int $offset): array
    {
        // Name columns explicitly - never SELECT * in production code
        $stmt = $this->db->prepare(
            "SELECT id, title, content, created_at FROM tbl_resources ORDER BY id DESC LIMIT ? OFFSET ?"
        );
        $stmt->execute([$perPage, $offset]);
        return $stmt->fetchAll(\PDO::FETCH_ASSOC);
    }

    public function count(): int
    {
        return (int)$this->db->query("SELECT COUNT(*) FROM tbl_resources")->fetchColumn();
    }

    public function findById(int $id): ?array
    {
        $stmt = $this->db->prepare("SELECT id, title, content, created_at FROM tbl_resources WHERE id = ?");
        $stmt->execute([$id]);
        $row = $stmt->fetch(\PDO::FETCH_ASSOC);
        return $row ?: null;
    }

    public function create(array $data): int
    {
        $stmt = $this->db->prepare(
            "INSERT INTO tbl_resources (title, content) VALUES (?, ?)"
        );
        $stmt->execute([$data['title'], $data['content']]);
        return (int)$this->db->lastInsertId();
    }
}

<?php
namespace Scriptlog\Service;

class MyResourceService
{
    private $resourceDao;

    public function __construct($resourceDao)
    {
        $this->resourceDao = $resourceDao;
    }

    public function getPaginatedResources(int $page, int $perPage): array
    {
        $offset = ($page - 1) * $perPage;
        return [
            'items' => $this->resourceDao->findAll($perPage, $offset),
            'total' => $this->resourceDao->count()
        ];
    }

    public function getResource(int $id): ?array
    {
        return $this->resourceDao->findById($id);
    }

    public function createResource(array $data): int
    {
        return $this->resourceDao->create($data);
    }
}

<?php
namespace Scriptlog\Controller\Api;

use Scriptlog\Core\ApiResponse;
use Scriptlog\Dto\Api\MyResourceApiDto;

class MyResourceApiController extends \Scriptlog\Controller\ApiController
{
    private $resourceService;
    private $hateoas;

    public function __construct($resourceService)
    {
        // Public by default: set requiresAuth BEFORE parent::__construct(),
        // which is where authenticate() runs. Setting it later inside an
        // action has no effect on the constructor's 401 check.
        $this->requiresAuth = false;

        parent::__construct();
        $this->resourceService = $resourceService;
        $this->hateoas = new \Scriptlog\Core\ApiHateoas();
    }

    public function index($params = [])
    {
        $pagination = $this->getPagination($params);

        try {
            $result = $this->resourceService->getPaginatedResources(
                $pagination['page'],
                $pagination['per_page']
            );
            $transformed = MyResourceApiDto::transformCollection(
                $result['items'],
                $this->getAppUrl(),
                $this->hateoas
            );
            ApiResponse::paginated(
                $transformed,
                $pagination['page'],
                $pagination['per_page'],
                $result['total']
            );
        } catch (\Throwable $e) {
            ApiResponse::error($e->getMessage(), 500, 'FETCH_ERROR');
        }
    }

    public function show($params = [])
    {
        $id = isset($params['id']) ? (int)$params['id'] : 0;

        if (!$id) {
            ApiResponse::badRequest('Resource ID is required');
            return;
        }

        $resource = $this->resourceService->getResource($id);

        if (!$resource) {
            ApiResponse::notFound('Resource not found');
            return;
        }

        ApiResponse::success(
            MyResourceApiDto::transform($resource, $this->getAppUrl(), $this->hateoas)
        );
    }

    public function store($params = [])
    {
        $this->requiresAuth = true;

        if (!$this->hasPermission(['administrator', 'editor'])) {
            ApiResponse::forbidden('Permission denied');
            return;
        }

        $errors = $this->validateRequired($this->requestData, ['title', 'content']);

        if ($errors) {
            ApiResponse::unprocessableEntity('Validation failed', $errors);
            return;
        }

        $id = $this->resourceService->createResource($this->requestData);
        ApiResponse::created(['id' => $id], 'Resource created');
    }
}

$router->get('resources', 'MyResourceApiController@index');
$router->get('resources/(?P<id>[0-9]+)', 'MyResourceApiController@show');
$router->post('resources', 'MyResourceApiController@store');
$router->put('resources/(?P<id>[0-9]+)', 'MyResourceApiController@update');
$router->patch('resources/(?P<id>[0-9]+)', 'MyResourceApiController@update');
$router->delete('resources/(?P<id>[0-9]+)', 'MyResourceApiController@destroy');