Blog JSON:API
v0.0.1
The blog exposes its records through the CMS's JSON:API. Readers use one set of routes, site admins another, and masters a third. This page lists the routes, how to authenticate, and one example that signs in, creates a post and schedules it. Record fields are listed in Blog record fields.
Connect
- Every route is under
/api/jsonon the site's own host. The host decides which site a request is for. - Send
content-type: application/vnd.api+jsonandaccept: application/vnd.api+json. - Sign in with
POST /api/json/v1/auth/user/sign-in. The token is inmeta.tokenof the answer. Send it asauthorization: Bearer <token>. - A master account has no site. On the master site's address, add the header
x-no-tenant: trueto leave the request unscoped. - The interactive spec is at
/api/json/swaggeruiand the OpenAPI document at/api/json/open_api. Both need an API permission.
Route groups
Prefix under /api/json | For | Needs |
|---|---|---|
/v1/user/mishka-blog | Readers | Reads need no token. Writes need a signed-in user. |
/v1/tenant/admin/mishka-blog | Site admins, on their own site | admin:api:blog:post or admin:api:blog:comment, as the record asks. |
/v1/master/admin/mishka-blog | Masters, on any site | The same names. A create takes a site_id. |
The record types are blog_post, collection, tag, blogger, team, comment and auto_posting. Lists are paged by offset, 20 to a page and at most 100, and accept page[limit]. The /post/featured list takes 10 to a page and at most 50.
Reader routes
Route under /v1/user/mishka-blog | Method | What it does |
|---|---|---|
/post/published | GET | Lists published posts the caller may open. |
/post/published/:id | GET | Reads one published post. |
/collection/active, /collection/active/:id | GET | Lists or reads active collections. |
/tag, /tag/:id | GET | Lists or reads tags. |
/blogger, /blogger/:id, /blogger/by-slug/:slug | GET | Lists or reads bloggers that are not archived. |
/team, /team/:id, /team/by-slug/:slug | GET | Lists or reads active teams. |
/comment/approved | GET | Lists the approved comments of a post. Pass post_id. |
/comment/create | POST | Writes a comment as the signed-in user. It starts as pending. Attributes: post_id, content, optional parent_comment_id. |
/comment/my-comments | GET | Lists the caller's comments. |
/post-rating, /post-rating/my-ratings, /post-rating/:id | POST, GET, DELETE | Rates a post (post_id, rating from 1 to 5), lists the caller's ratings, removes one. |
/bookmark, /bookmark/my-bookmarks, /bookmark/:id | POST, GET, DELETE | Bookmarks a post (post_id), lists the caller's bookmarks, removes one. |
/comment-vote, /comment-vote/my-votes, /comment-vote/:id | POST, GET, DELETE | Votes on a comment (comment_id, vote_type of up or down), lists the caller's votes, removes one. |
/blogger-follow, /blogger-follow/my-follows, /blogger-follow/followers, /blogger-follow/:id | POST, GET, PATCH, DELETE | Follows a blogger (blogger_id), lists the caller's follows, lists a blogger's followers (blogger_id), changes notification_enabled, unfollows. |
/team-follow, /team-follow/my-following, /team-follow/:id | POST, GET, PATCH, DELETE | The same for teams, with team_id. |
A comment, rating, bookmark or vote on a post that is locked to permissions the caller does not hold is refused as though the post were not there.
Admin routes
These routes exist under both /v1/tenant/admin/mishka-blog and /v1/master/admin/mishka-blog. Replace {record} with post, collection, tag, blogger, team, comment or auto-posting.
| Route | Method | Records | What it does |
|---|---|---|---|
/{record} | GET, POST | All | Lists records, or creates one. The master prefix has no route to create a comment. |
/{record}/:id | GET, PATCH | All | Reads or updates one. |
/{record}/language-variants | GET | Post, collection, tag | Lists the editions of a language group. Pass language_group_id. |
/{record}/archived, /{record}/archived/:id | GET | All | Lists or reads archived records. |
/{record}/:id/archive | DELETE | All | Archives a record. |
/{record}/:id/unarchive | PATCH | All | Restores an archived record. |
/{record}/:id/permanent | DELETE | All | Deletes a record for good. |
/{record}/:id/with-versions | GET | All but comment | Reads a record with its versions. |
/{record}/:record_id/versions | GET | All but comment | Lists a record's versions. |
/{record}/:id/version/:version_id/restore | PATCH | All but comment | Restores a version. |
/{record}/:record_id/version/:version_id/preview | GET | All but comment | Returns the record with that version's values, without saving. |
/post/:id/publish, /post/:id/unpublish | PATCH | Post | Publishes, or returns to draft. |
/post/:id/schedule | PATCH | Post | Sets the status to scheduled. Attribute: scheduled_publish_at. |
/post/published, /post/drafts, /post/scheduled, /post/featured | GET | Post, tenant prefix only | Lists posts by status, or the featured ones. |
/comment/:id/approve, /flag, /mark-spam, /pin, /unpin | PATCH | Comment | Moderates a comment. |
/blogger/by-user/:user_id, /blogger/by-slug/:slug | GET | Blogger | Finds a profile by account or slug. |
/team/by-slug/:slug | GET | Team | Finds a team by slug. |
/auto-posting/by-plugin/:plugin, /auto-posting/active | GET | Auto posting | Finds a configuration by plugin, or lists the active ones. |
/auto-posting/:id/activate, /deactivate | PATCH | Auto posting | Switches a configuration on or off. |
A post can include its collections, tags, comments and bloggers. On the admin prefixes the names are tenant_collections and so on, or master_collections and so on, and tenant_comments returns comments in every status. A blogger's account email is not in a normal answer. Ask for it with fields[blogger]=author_email, as a holder of the post area.
Example: sign in, create a post, schedule it
Sign in. Use the site's own host.
curl -X POST https://example.com/api/json/v1/auth/user/sign-in \
-H "content-type: application/vnd.api+json" \
-H "accept: application/vnd.api+json" \
-d '{"data": {"type": "user", "attributes": {"email": "[email protected]", "password": "your password"}}}'Create a draft with the token from meta.token:
curl -X POST https://example.com/api/json/v1/tenant/admin/mishka-blog/post \
-H "authorization: Bearer $TOKEN" \
-H "content-type: application/vnd.api+json" \
-H "accept: application/vnd.api+json" \
-d '{"data": {"type": "blog_post", "attributes": {"title": "Hello", "slug": "hello", "content": "<p>First post</p>", "status": "draft"}}}'Schedule it with a future date. The answer shows status as scheduled:
curl -X PATCH https://example.com/api/json/v1/tenant/admin/mishka-blog/post/$POST_ID/schedule \
-H "authorization: Bearer $TOKEN" \
-H "content-type: application/vnd.api+json" \
-H "accept: application/vnd.api+json" \
-d '{"data": {"type": "blog_post", "attributes": {"scheduled_publish_at": "2030-01-01T09:00:00Z"}}}'A scheduled post stays out of the reader routes. Publish it with the /publish route when its time comes.