Skip to content

🌐 Gold Standard REST API Reference

Complete API documentation for integrating with the Gold Standard module.

Base URL: https://yoursite.com/api/v1/goldstandard

Authentication

All API requests require authentication via Bearer token or API key.

# Bearer Token
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# API Key
X-API-Key: gs_live_abc123def456

Obtaining Tokens

POST /api/v1/auth/login
Content-Type: application/json

{
    "username": "user@example.com",
    "password": "your_password"
}

Response: 

{
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIs...",
        "token_type": "Bearer",
        "expires_in": 3600
    }
}

API Overview

flowchart LR
    subgraph Endpoints["API Endpoints"]
        ART[/articles]
        CAT[/categories]
        TAG[/tags]
        CMT[/comments]
        USR[/authors]
    end

    subgraph Methods["HTTP Methods"]
        GET[GET]
        POST[POST]
        PUT[PUT]
        DEL[DELETE]
    end

    Methods --> Endpoints

Articles

List Articles

GET /articles

Query Parameters:

Parameter Type Default Description
page integer 1 Page number
per_page integer 15 Items per page (max 100)
status string published Filter by status
category integer - Filter by category ID
author integer - Filter by author ID
tag string - Filter by tag slug
search string - Search in title and content
sort string published_at Sort field
order string desc Sort order (asc/desc)
include string - Include relations (author,category,tags)

Response:

Note: Article IDs use XMF ULID format (26 characters, lexicographically sortable).

{
    "data": [
        {
            "id": "01HV8X5Z0KDMVR8SDPY62J9ACP",
            "type": "article",
            "attributes": {
                "title": "Getting Started with XOOPS 2026",
                "slug": "getting-started-xoops-2026",
                "excerpt": "Learn how to build modern XOOPS modules...",
                "status": "published",
                "views": 1250,
                "reading_time": 8,
                "created_at": "2026-01-15T10:30:00Z",
                "updated_at": "2026-01-20T14:45:00Z",
                "published_at": "2026-01-15T12:00:00Z"
            },
            "relationships": {
                "author": {
                    "data": {"type": "author", "id": "01HV8X4A0KAUTHOR00000000001"}
                },
                "category": {
                    "data": {"type": "category", "id": "01HV8X4B0KCATEG000000000005"}
                },
                "tags": {
                    "data": [
                        {"type": "tag", "id": "01HV8X4C0KTAG0000000000001"},
                        {"type": "tag", "id": "01HV8X4C0KTAG0000000000003"}
                    ]
                }
            },
            "links": {
                "self": "/api/v1/goldstandard/articles/01HV8X5Z0KDMVR8SDPY62J9ACP",
                "web": "/articles/getting-started-xoops-2026"
            }
        }
    ],
    "included": [
        {
            "id": "01HV8X4A0KAUTHOR00000000001",
            "type": "author",
            "attributes": {
                "name": "John Doe",
                "avatar": "https://example.com/avatars/john.jpg"
            }
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 15,
        "total": 47,
        "last_page": 4,
        "total_published": 42,
        "total_draft": 5
    },
    "links": {
        "first": "/api/v1/goldstandard/articles?page=1",
        "last": "/api/v1/goldstandard/articles?page=4",
        "prev": null,
        "next": "/api/v1/goldstandard/articles?page=2"
    }
}

Get Single Article

GET /articles/{id}

Path Parameters:

Parameter Type Description
id string (ULID) Article ID (26-character XMF ULID)

Query Parameters:

Parameter Type Description
include string Include relations (author,category,tags,comments)

Response:

{
    "data": {
        "id": "01HV8X5Z0KDMVR8SDPY62J9ACP",
        "type": "article",
        "attributes": {
            "title": "Getting Started with XOOPS 2026",
            "slug": "getting-started-xoops-2026",
            "content": "<p>Full article content in HTML...</p>",
            "excerpt": "Learn how to build modern XOOPS modules...",
            "status": "published",
            "views": 1250,
            "word_count": 1560,
            "reading_time": 8,
            "created_at": "2026-01-15T10:30:00Z",
            "updated_at": "2026-01-20T14:45:00Z",
            "published_at": "2026-01-15T12:00:00Z"
        },
        "relationships": {
            "author": {
                "data": {"type": "author", "id": "01HV8X4A0KAUTHOR00000000001"}
            },
            "category": {
                "data": {"type": "category", "id": "01HV8X4B0KCATEG000000000005"}
            },
            "tags": {
                "data": [
                    {"type": "tag", "id": "01HV8X4C0KTAG0000000000001"},
                    {"type": "tag", "id": "01HV8X4C0KTAG0000000000003"}
                ]
            }
        }
    }
}

Create Article

POST /articles
Content-Type: application/json
Authorization: Bearer {token}

Request Body:

{
    "title": "My New Article",
    "content": "<p>Article content here...</p>",
    "category_id": "01HV8X4B0KCATEG000000000005",
    "tags": ["xoops", "tutorial", "php"],
    "status": "draft",
    "publish_at": null
}

Validation Rules:

Field Rules
title Required, string, 3-255 characters
content Required, string, min 50 characters
category_id Required, ULID string, must exist
tags Optional, array, max 10 items
tags.* String, max 50 characters
status Optional, enum: draft, published
publish_at Optional, ISO 8601 datetime, future date

Response (201 Created):

{
    "data": {
        "id": "01HV8X5Z0KDMVR8SDPY62J9ACQ",
        "type": "article",
        "attributes": {
            "title": "My New Article",
            "slug": "my-new-article",
            "status": "draft",
            "created_at": "2026-01-29T10:00:00Z"
        }
    },
    "links": {
        "self": "/api/v1/goldstandard/articles/01HV8X5Z0KDMVR8SDPY62J9ACQ"
    }
}

Update Article

PUT /articles/{id}
Content-Type: application/json
Authorization: Bearer {token}

Request Body:

{
    "title": "Updated Title",
    "content": "<p>Updated content...</p>",
    "category_id": "01HV8X4B0KCATEG000000000006"
}

Response (200 OK):

{
    "data": {
        "id": "01HV8X5Z0KDMVR8SDPY62J9ACP",
        "type": "article",
        "attributes": {
            "title": "Updated Title",
            "updated_at": "2026-01-29T15:30:00Z"
        }
    }
}

Delete Article

DELETE /articles/{id}
Authorization: Bearer {token}

Response (204 No Content)

Publish Article

POST /articles/{id}/publish
Authorization: Bearer {token}

Response (200 OK):

{
    "data": {
        "id": "01HV8X5Z0KDMVR8SDPY62J9ACP",
        "type": "article",
        "attributes": {
            "status": "published",
            "published_at": "2026-01-29T16:00:00Z"
        }
    },
    "message": "Article published successfully"
}

Archive Article

POST /articles/{id}/archive
Authorization: Bearer {token}

Response (200 OK):

{
    "data": {
        "id": "01HV8X5Z0KDMVR8SDPY62J9ACP",
        "type": "article",
        "attributes": {
            "status": "archived"
        }
    },
    "message": "Article archived successfully"
}

Categories

List Categories

GET /categories

Response:

{
    "data": [
        {
            "id": "01HV8X4B0KCATEG000000000001",
            "type": "category",
            "attributes": {
                "name": "Tutorials",
                "slug": "tutorials",
                "description": "Step-by-step tutorials",
                "article_count": 15,
                "parent_id": null
            },
            "children": [
                {
                    "id": "01HV8X4B0KCATEG000000000004",
                    "type": "category",
                    "attributes": {
                        "name": "Beginner",
                        "slug": "beginner",
                        "article_count": 8,
                        "parent_id": "01HV8X4B0KCATEG000000000001"
                    }
                }
            ]
        }
    ]
}

Get Category

GET /categories/{id}

Category Articles

GET /categories/{id}/articles

Tags

List Tags

GET /tags

Query Parameters:

Parameter Type Description
limit integer Max tags to return (default 50)
min_count integer Minimum article count

Response:

{
    "data": [
        {
            "id": "01HV8X4C0KTAG0000000000001",
            "type": "tag",
            "attributes": {
                "name": "XOOPS",
                "slug": "xoops",
                "article_count": 25
            }
        },
        {
            "id": "01HV8X4C0KTAG0000000000002",
            "type": "tag",
            "attributes": {
                "name": "PHP 8",
                "slug": "php-8",
                "article_count": 18
            }
        }
    ]
}

Tag Articles

GET /tags/{slug}/articles

Comments

List Article Comments

GET /articles/{id}/comments

Response:

{
    "data": [
        {
            "id": "01HV8X4D0KCOMMENT0000000001",
            "type": "comment",
            "attributes": {
                "content": "Great article, thanks!",
                "status": "approved",
                "created_at": "2026-01-20T09:15:00Z"
            },
            "relationships": {
                "author": {
                    "data": {"type": "user", "id": "01HV8X4A0KAUTHOR00000000042"}
                }
            }
        }
    ],
    "meta": {
        "total": 12
    }
}

Create Comment

POST /articles/{id}/comments
Content-Type: application/json
Authorization: Bearer {token}

Request Body:

{
    "content": "This was really helpful, thank you!"
}

Error Responses

Validation Error (422)

{
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "The given data was invalid.",
        "details": [
            {
                "field": "title",
                "message": "The title field is required."
            },
            {
                "field": "content",
                "message": "The content must be at least 50 characters."
            }
        ]
    }
}

Not Found (404)

{
    "error": {
        "code": "NOT_FOUND",
        "message": "Article not found."
    }
}

Unauthorized (401)

{
    "error": {
        "code": "UNAUTHORIZED",
        "message": "Invalid or expired authentication token."
    }
}

Forbidden (403)

{
    "error": {
        "code": "FORBIDDEN",
        "message": "You do not have permission to perform this action."
    }
}

Rate Limited (429)

{
    "error": {
        "code": "RATE_LIMITED",
        "message": "Too many requests. Please try again later.",
        "retry_after": 60
    }
}

Rate Limits

Endpoint Type Limit Window
Read (GET) 100 1 minute
Write (POST/PUT) 20 1 minute
Delete 10 1 minute

Rate Limit Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1706529600

Webhooks

Configure webhooks to receive real-time notifications.

Available Events

Event Description
article.created New article created
article.published Article published
article.updated Article updated
article.deleted Article deleted
comment.created New comment added

Webhook Payload

{
    "event": "article.published",
    "timestamp": "2026-01-29T16:00:00Z",
    "data": {
        "id": "01HV8X5Z0KDMVR8SDPY62J9ACP",
        "type": "article",
        "attributes": {
            "title": "Article Title",
            "slug": "article-title"
        }
    }
}

SDK Examples

PHP

<?php

use GoldStandard\ApiClient;

$client = new ApiClient('your-api-key');

// List articles
$articles = $client->articles()->list([
    'status' => 'published',
    'per_page' => 10,
]);

// Create article
$article = $client->articles()->create([
    'title' => 'New Article',
    'content' => 'Content here...',
    'category_id' => 5,
]);

// Publish article
$client->articles()->publish($article->id);

JavaScript

import { GoldStandardClient } from '@xoops/goldstandard-sdk';

const client = new GoldStandardClient({
    apiKey: 'your-api-key',
    baseUrl: 'https://yoursite.com/api/v1/goldstandard'
});

// List articles
const { data, meta } = await client.articles.list({
    status: 'published',
    include: ['author', 'tags']
});

// Create article
const article = await client.articles.create({
    title: 'New Article',
    content: 'Content here...',
    categoryId: 5
});

api #rest #endpoints #reference #goldstandard