API Floryan Simar

Points de terminaison de l’API

Tous les points de terminaison renvoient application/json et autorisent les requêtes GET depuis une autre origine. L’API est décrite par un document OpenAPI 3.1, pour que les agents puissent découvrir les opérations, leurs paramètres typés et leurs schémas de réponse sans lire cette page.

• GET /api — Index de toutes les opérations, avec l’URL du document OpenAPI.
• GET /api/v1/profile — Identité, localisation, disponibilité, compétences et liens canoniques.
• GET /api/v1/posts — Articles publiés, du plus récent au plus ancien, avec slug, date, tags et URL.
• GET /api/v1/posts/{slug} — Un article avec ses métadonnées et sa source Markdown.
• GET /api/v1/health — Sonde de disponibilité : statut et service.

Erreurs

Quand un gestionnaire répond, le corps est en JSON. Le site est toutefois prerendu en fichiers statiques : seuls GET et HEAD sur une route construite atteignent l’API. Un chemin inconnu, une méthode autre que GET, ou un slug sans article publié est traité par la page 404 ou 405 de l’hébergeur. Les slugs viennent de /api/v1/posts. La forme de l’erreur est 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."
  }
}

Les codes sont lisibles par une machine : not_found, post_not_found, invalid_slug et method_not_allowed.

Essayer

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/

Négociation de contenu

GET / avec Accept: text/markdown renvoie la page d’accueil en Markdown (text/markdown, Vary: Accept). Avec Accept: text/html, il renvoie la page normale. Toutes les autres pages sont du HTML statique : leur texte est présent dans la première réponse, sans exécuter de JavaScript.

Fichiers lisibles par les machines

• /llms.txt — quand utiliser ce site, comment l’appeler et où se trouvent les pages.
• /openapi.json — la description OpenAPI 3.1 de l’API.
• /sitemap.xml — chaque URL indexable avec une date lastmod.
• /robots.txt — les règles de crawl et l’emplacement du sitemap.
• Chaque page HTML embarque du JSON-LD schema.org pour la Personne, l’Organisation professionnelle et le site Web.

Mise en cache

Les réponses de l’API sont mises en cache cinq minutes ; le document OpenAPI et les fichiers lisibles par les machines pendant une heure. La sonde de disponibilité n’est jamais mise en cache. Les réponses de document portent Vary: Accept pour que les caches gardent les variantes HTML et Markdown séparées.