Floryan Simar API

API endpoints

Every endpoint returns application/json and allows cross-origin GET requests. The API is described by an OpenAPI 3.1 document, so agents can discover the operations, their typed parameters and their response schemas without reading this page.

• GET /api — Index of every operation, with the OpenAPI document URL.
• GET /api/v1/profile — Identity, location, availability, skills and canonical links.
• GET /api/v1/posts — Published blog posts, newest first, with slug, date, tags and URL.
• GET /api/v1/posts/{slug} — One post with its metadata and Markdown source.
• GET /api/v1/health — Liveness probe: status and service.

Errors

When a handler answers, the body is JSON. The site is prerendered as static files, though, so only GET and HEAD on a route that was built reaches the API: an unknown path, a non-GET method, or a post slug with no published post is answered by the host's own 404 or 405 page. Slugs come from /api/v1/posts. The error shape is stable:

{
  "error": {
    "code": "not_found",
    "message": "No API route matches /api/v1/nope.",
    "hint": "See https://www.theyoxy.be/openapi.json for the available operations."
  }
}

Codes are machine-readable: not_found, post_not_found, invalid_slug and method_not_allowed.

Try it

curl -sS https://www.theyoxy.be/api/v1/profile
curl -sS https://www.theyoxy.be/api/v1/posts
curl -sS -H 'Accept: text/markdown' https://www.theyoxy.be/

Content negotiation

GET / with Accept: text/markdown returns the homepage as Markdown (text/markdown, Vary: Accept). With Accept: text/html it returns the normal page. Every other page is static HTML, so its text is in the first response without running JavaScript.

Machine-readable files

• /llms.txt — when to use this site, how to call it, and where the pages are.
• /openapi.json — the OpenAPI 3.1 description of the API.
• /sitemap.xml — every indexable URL with a lastmod date.
• /robots.txt — crawl rules and the sitemap location.
• Every HTML page embeds schema.org JSON-LD for the Person, the professional Organization and the WebSite.

Caching

API responses are cached for five minutes; the OpenAPI document and the machine-readable files for an hour. Health is never cached. Document responses carry Vary: Accept so caches keep the HTML and Markdown variants apart.