Blog-Core - HTTP API

HTTP API

The HTTP API expects header 'X-Key' to be set for authenticated requests. The key is obtained by logging in using the /api/auth endpoint.

Input to the API requests must be a JSON document with the required fields. The only exception is the file upload endpoint.

Successful API responses will have status code 200 and the response in the following JSON format:

{ "status": "success", "data": data ... }

Unsuccessful (validation error/no permissions/etc) responses also have status code 200 but the response is in the following format:

{ "status": "error", "message": "Message explaining the error." }

All API calls are subject to permissions checking as described here.

Users

Authenticate

Request URL: /api/auth, type POST.

Fields:

username
password

Returned fields:

id
type
key

Example output:

{
    "status":"success",
    "data": {
        "id":"3a388c86-3a78-4e8b-a254-377788c143e0",
        "key":"b0fa25aa-6f86-436f-a6f8-fe03c509f4be",
        "type":"admin"
    }
}

Current user info

Request URL: /api/user/info, type GET.

Returned fields:

$id
type
fullname
username

Add a new user

Request URL: /api/user, type POST.

Fields:

username - must match email address pattern.
fullname - must be set.
password - minimum length 6, optional.
type - either admin or author.
link - user link, can be empty string.

Returns user id. Requires the current user to be an admin.

Retrieve the existing user

Request URL: /api/user/Id, type GET.

Returned fields:

$id
username
fullname
type
link

Requires the current user to be an admin.

Modify the existing user

Request URL: /api/user/Id, type PUT.

Fields:

username - must match email address pattern.
fullname - must be set.
password - minimum length 6, optional.
type - either admin or author.
link - user link, can be empty string.

Returns user id. Requires the current user to be an admin. When the password is not set then it is not changed.

Remove the existing user

Request URL: /api/user/Id, type DELETE.

Returns the removed user id. Requires the current user to be an admin.

List of users

Request URL: /api/users, type GET.

Returned fields:

$id
username
fullname
type

Requires the current user to be an admin.

Entries (posts)

Entry types

Request URL: /api/types, type GET.

Retrieves array of entry types that the current user has access to.

Fields:

comments (boolean)
grants (array of user's role grants for the type)
label
menu_label
preview (URL pattern containing <slug> placeholder). Could be null

Entry type info

Request URL: /api/type/Type, type GET.

Retrieves the given type info. Requires user to have access to the type.

Fields:

comments (boolean)
grants (array of user's role grants for the type)
label
menu_label
preview (URL pattern containing <slug> placeholder). Could be null

Add a new entry

Request URL: /api/entry, type POST.

Fields:

title
slug
tags (array of strings)
date_published (optional)
date_updated
commenting (boolean)
published (boolean)
content
content_type (enum markdown/raw)
description
type
language (language identifier)

Returns the saved post id. Subject to entry access control.

Retrieve the existing entry

Request URL: /api/entry/Id, type GET.

Returned fields:

$id
slug
type
date_published
date_updated
commenting
published
title
author
content
description
content_type
tags
comments (comments count)

Subject to entry access control.

Retrieve the existing entry info

Request URL: /api/entry/Id/info, type GET.

Same as /api/entry/Id but does not retrieve the content field.

Update the existing entry

Request URL: /api/entry/Id, type PUT.

Fields:

author
title
slug
tags (array of strings)
date_published (optional)
date_updated
commenting (boolean)
published (boolean)
content
content_type (enum markdown/raw)
description
type
language (language identifier)

Subject to entry access control. Only an admin can change author and type value as they change entry access rules.

Remove the existing entry

Request URL: /api/entry/Id, type DELETE.

Returns the removed entry id. Entry comments are removed. Entry files are removed. Subject to entry access control.

List of entries

Request URL: /api/entries/Type, type GET.

Returned fields:

$id
slug
type
date_published
date_updated
commenting
published
title
author

Subject to entry access control.

Entry files

Request URL: /api/files/EntryId, type GET.

Retrieves the array of files associated with the entry.

Fields:

name

Subject to entry access control.

Upload a file

Request URL: /api/upload/EntryId, type POST.

The request body must contain the file. The file name must be in the header X-File-Name. Subject to entry access control. Returns value true when upload was successful.

Remove a file

Request URL: /api/file/EntryId/Name, type DELETE.

Subject to entry access control. Returns value true when removal was successful.

Comments

Add a new comment

Request URL: /api/post/Id/comment, type POST.

Fields:

author
email (optional)
site (optional)
comment
content
reply_to (optional)
question (integer)
answer

This endpoint does not require authentication.

Tree of comments

Request URL: /api/post/Id/comments, type GET.

Returned fields:

$id
author
email (optional)
site (optional)
comment
content
reply_to (optional)
comments (array of replies)

Does not require authentication. Comments in a single node are ordered by date in descending order.

Remove the existing comment

Request URL: /api/comment/EntryId/CommentId, type DELETE.

Subject to entry access control.

Human check question

Request URL: /api/question, type GET.

Returned fields:

question (string)
id (number)

Does not require authentication.

Configuration entries

List of entries

Request URL: /api/configs, type GET.

Returned fields:

name
value

Requires admin privileges.

Update the config entry

Request URL: /api/configs, type PUT.

Fields:

name
value

Requires admin privileges. If the config entry does not exist then it will be added.