API

We provide an API to allow programmatic updating of one’s blog.

API Key

your-api-key

Notes

• One can reset their API key. This will invalidate their key and issue a new one.
• The API is at https://mataroa.blog/api/
• All API endpoints end with a trailing slash.
• Content type application/json is expected.
• There is no rate limiting.

Authentication

We authenticate requests using the Authorization HTTP header, using the Bearer scheme.

Authorization: Bearer your-api-key

POST /api/posts/

Create new post.

• title: string [required]
• body: string [optional]
• published_at: string (ISO date eg. 2006-01-31) [optional]

{
    "title": "New blog",
    "body": "## Why?\n\nEveryone wants a blog, right?",
    "published_at": "2020-09-21"
}

{
    "ok": true,
    "slug": "new-blog",
    "url": "https://your-username.mataroa.blog/blog/new-blog/"
}

$ curl -X POST \
    -H 'Authorization: Bearer your-api-key' \
    -d '{"title": "New blog", "body": "## Why?\n\nEveryone needs a blog, right?"}' \
    https://mataroa.blog/api/posts/

GET /api/posts/<post-slug>/

Get single post.

• (no parameters)

{
    "ok": true,
    "slug": "new-blog",
    "title": "New blog",
    "body": "Welcome!"
    "published_at": "2020-09-21"
    "url": "https://your-username.mataroa.blog/blog/new-blog/"
}

$ curl -X GET \
    -H 'Authorization: Bearer your-api-key' \
    https://mataroa.blog/api/posts/new-blog/

PATCH /api/posts/<post-slug>/

Update existing post.

• title: string [optional]
• slug: string (slug; no spaces) [optional]
• body: string [optional]
• published_at: string (ISO date eg. 2006-01-31; or empty to unpublish) [optional]

{
    "title": "Updating my new blog",
    "slug": "updating-blog",
    "body": "Welcome back!"
    "published_at": "2020-09-21"
}

{
    "ok": true,
    "slug": "updating-blog",
    "url": "https://your-username.mataroa.blog/blog/updating-blog/"
}

$ curl -X PATCH \
    -H 'Authorization: Bearer your-api-key' \
    -d '{"title": "Updating my new blog", "body": "Rethinking and rewriting."}' \
    https://mataroa.blog/api/posts/introducing-my-new-blog/

DELETE /api/posts/<post-slug>/

Delete post.

• (no parameters)

{
    "ok": true
}

$ curl -X DELETE \
    -H 'Authorization: Bearer your-api-key' \
    https://mataroa.blog/api/posts/introducing-my-new-blog/

GET /api/posts/

List all posts.

• (no parameters)

{
    "ok": true,
    "post_list": [
        {
            "title": "On life",
            "slug": "on-life",
            "body": "What is life?\n\nAn illusion, a shadow, a story.",
            "published_at": null,
            "url": "https://your-username.mataroa.blog/blog/on-life/"
        },
        {
            "title": "New blog",
            "slug": "new-blog",
            "body": "With health!",
            "published_at": "2020-10-19",
            "url": "https://your-username.mataroa.blog/blog/new-blog/"
        }
    ]
}

$ curl -X GET \
    -H 'Authorization: Bearer your-api-key' \
    https://mataroa.blog/api/posts/