Posts & Blog API

This section describes the API endpoints for managing and retrieving blog posts, announcements, and pages.

Public Endpoints

List Posts

Retrieve a list of active posts, optionally filtered by type.

Endpoint: GET /api/posts

Query Parameters:

  • type (optional): Filter by post type (e.g., blog, announcement, page). Defaults to blog.
  • locale (optional): Active locale code (e.g., en, zh). When multi-language is enabled and type=blog, only blog posts bound to the requested locale (or legacy unbound posts with locale = null) are returned.
  • category (optional): Filter by category slug. An unknown or inactive slug returns an empty list rather than falling back to all posts. all is ignored.

Response:

{
  "data": [
    {
      "id": 1,
      "slug": "getting-started",
      "title": "Getting Started with APayShop",
      "description": "Learn how to set up your store in minutes.",
      "imageUrl": "https://example.com/image.jpg",
      "type": "blog",
      "locale": "en",
      "categoryId": 3,
      "category": { "id": 3, "slug": "tutorials", "name": "Tutorials", "description": null },
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-02T00:00:00.000Z"
    }
  ],
  "total": 1
}

category is null when the post is uncategorized; the name is localized to the request language.

List Post Categories

Retrieve the active blog categories, ordered by sort then id, with names localized to the request language.

Endpoint: GET /api/post-categories

Response:

{
  "data": [
    { "id": 3, "slug": "tutorials", "name": "Tutorials", "description": null, "sort": 0 }
  ]
}

Get Post by Slug

Retrieve a single active post by its unique slug. When multi-language is enabled and a blog post is bound to a specific locale (e.g., zh), visiting a non-matching storefront URL (such as /blog/:slug) automatically 301-redirects to the post's bound locale URL (/zh/blog/:slug).

Endpoint: GET /api/posts/:slug

Query Parameters:

  • locale (optional): Active locale code (e.g., en, zh).

Response:

{
  "id": 1,
  "slug": "getting-started",
  "title": "Getting Started with APayShop",
  "content": "<p>This is the full HTML content of the post...</p>",
  "description": "Learn how to set up your store in minutes.",
  "imageUrl": "https://example.com/image.jpg",
  "type": "blog",
  "locale": "en",
  "isActive": true,
  "metaData": null,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-02T00:00:00.000Z"
}

Admin Endpoints (Requires Authentication)

List All Posts

Retrieve a paginated list of all posts, including drafts.

Endpoint: GET /api/admin/posts

Query Parameters:

  • type (optional): Filter by post type (blog, changelog, announcement, page).
  • locale (optional): Filter by bound post locale (e.g., en, zh).
  • status (optional): Filter by published or draft.
  • category (optional): Filter by category id, or uncategorized / none for posts without a category.
  • search (optional): Keyword search across title, slug, key, and description.

Create Post

Create a new post. When type is blog, locale binds the blog post to a single language (en, zh, etc.). Other post types (changelog, announcement, page) store locale = null and use metaData.translations.

Endpoint: POST /api/admin/posts

Body:

{
  "slug": "new-blog-post",
  "title": "New Feature Release",
  "description": "We just released a great new feature.",
  "content": "<p>Details here...</p>",
  "type": "blog",
  "locale": "en",
  "categoryId": 3,
  "imageUrl": "https://example.com/image2.jpg",
  "isActive": true
}

categoryId is optional; pass null (or 0/"") for uncategorized.

Update Post

Update an existing post.

Endpoint: PUT /api/admin/posts/:id

Delete Post

Delete a post permanently.

Endpoint: DELETE /api/admin/posts/:id

List Post Categories

Retrieve all categories (including inactive) with a postCount of posts assigned to each.

Endpoint: GET /api/admin/posts/categories

Create Post Category

Endpoint: POST /api/admin/posts/categories

Body:

{
  "slug": "tutorials",
  "name": "Tutorials",
  "description": "Step-by-step guides.",
  "sort": 0,
  "isActive": true,
  "locales": { "zh": { "name": "教程", "description": "分步指南" } }
}

slug must be lowercase letters, digits and hyphens, and unique. locales is an optional Record<lang, { name?, description? }>; each language falls back to the top-level name/description when omitted.

Get / Update / Delete Post Category

  • GET /api/admin/posts/categories/:id
  • PUT /api/admin/posts/categories/:id — same body as create; omit slug to keep the current one.
  • DELETE /api/admin/posts/categories/:id — posts using the category become uncategorized.