API de données

L’API de données retourne les données publiques du blog.

• Aucune clé API n’est requise.
• Toutes les réponses sont au format JSON.
• Tous les points de terminaison utilisent la méthode HTTP GET.
• Le chemin de base est : https://blogs.hyvor.com/api/data/v0/{subdomain}
• Par exemple, si votre blog se trouve à https://example.hyvor.com, le chemin de base est https://blogs.hyvor.com/api/data/v0/example
  • Remplacez {subdomain} par le sous-domaine de votre blog.

Points de terminaison

Objet unique

• /post - un article/page
• /tag
• /author
• /blog- paramètres du blog

Objets multiples

• /posts
• /posts/search - rechercher des articles
• /tags
• /authors

Réponse

Pour les points de terminaison à objet unique, la réponse est un objet. Par exemple, le point de terminaison /post retourne un objet Post (voir ci-dessous pour les définitions d’objets).

// A Post Object
{
    "id": 1000,
    "slug": "post",
    ...
}

Pour les points de terminaison à objets multiples, la réponse ressemble à ceci :

{
    "data": [{}, {}], // array of objects
    "pagination": {} // a Pagination object
}

Requête

Points de terminaison à objet unique

Pour /post, /tag, et /author

Le point de terminaison /blog n’accepte que language et keys en entrée.

Points de terminaison à objets multiples

/posts, /posts/search, /tags, et /authors

Le point de terminaison /posts/search a un paramètre search requis en plus des paramètres ci-dessus.

Le point de terminaison /tags dispose d’un paramètre visibility optionnel pour filtrer les étiquettes par visibilité. Notez que les étiquettes privées ne sont pas destinées à être affichées publiquement sur le blog. Elles ne doivent être utilisées qu’à des fins internes (par ex. : afficher/masquer un widget dans le blog si l’étiquette est présente dans l’article).

1. Le paramètre language

Si votre blog a plusieurs langues, vous pouvez définir le paramètre language avec un code de langue (ex : en, fr) d’une langue de votre blog. Si ce paramètre n’est pas fourni, la langue principale du blog est utilisée. Cette langue sera utilisée pour localiser les chaînes dans les articles, les auteurs, les étiquettes et le blog.

2. Le paramètre limit

Le paramètre limit peut être utilisé pour limiter le nombre d’enregistrements retournés dans les points de terminaison à objets multiples. La valeur par défaut est 25. Le maximum est 250.

3. Le paramètre page

Le paramètre page peut être utilisé pour paginer les résultats. Cela fonctionne en combinaison avec le paramètre limit. La valeur par défaut est 1.

To get the first 20 results: /posts?limit=20 To get the next 20 results (page 2):
/posts?limit=20&page=2

4. Le paramètre filter

Exemple : (published_at > 1639665890 & published_at < 1639695890) | is_featured=true

Notre API de données utilise Laravel FilterQ en interne, ce qui vous permet d’écrire une logique avancée comme dans l’exemple ci-dessus, en utilisant des opérateurs de comparaison et logiques.

Une condition se compose de trois parties :

• key
• operator
• value

Opérateurs

• = - égal à
• != - différent de
• > - supérieur à
• < - inférieur à
• >= - supérieur ou égal à
• <= - inférieur ou égal à

Valeurs

• null
• booléen : true ou false
• chaîne de caractères : 'hello' ou hello
  • Les chaînes sans guillemets doivent correspondre à [a-zA-Z_][a-zA-Z0-9_-]+ et ne peuvent pas être true, false, ou null.
• nombres : 250, -250,2.5

Opérateurs logiques

Vous pouvez utiliser des opérateurs logiques pour combiner plusieurs conditions.

• | - OU
• & - ET

Veuillez consulter la documentation FilterQ Expressions si vous avez besoin de plus de détails.

Clés prises en charge pour le filtrage

Valeurs de date

Voici quelques valeurs valides pour les clés de date.

• '2022-01-01'
• 'yesterday'
• 'first day of this year'
• 'last day of next month'
• '+1 day'
• '-1 week'
• 'next Thursday'
• 1639655890 - Horodatage UNIX

Par exemple : Dans le point de terminaison /posts, vous pouvez utiliser published_at>'-7 days' pour obtenir les articles publiés au cours des 7 derniers jours.

Exemples de filtrage

Pour obtenir les articles écrits par Alex :

// filter
author.slug=alex

// URL-encoded
/posts?filter=author.slug%3Dalex

Pour obtenir les articles à la une :

// filter
is_featured=true

// URL-encoded
/posts?filter=is_featured%3Dtrue

Pour obtenir les articles ayant l’étiquette audio ou video :

// filter
tag.slug=audio|tag.slug=video

// URL-encoded
/posts?filter=tag.slug%3Daudio%7Ctag.slug%3Dvideo

Pour obtenir les étiquettes ayant au moins 5 articles :

// filter
posts_count>=5

// URL-encoded
/tags?filter=posts_count%3E%3D5

Pour obtenir les auteurs ajoutés après le 1er janvier 2020 :

// filter
created_at>='2020-01-01'

// URL-encoded
/authors?filter=created_at%3E%3D%272020-01-01%27

Pour obtenir les articles publiés au cours des 7 derniers jours.

// filter
published_at>'-7 days'

// URL-encoded
/posts?filter=published_at%3E%27-7%20days%27

5. Le paramètre sort

Voici une liste des valeurs de tri prises en charge. Vous pouvez en combiner plusieurs sous forme de valeurs séparées par des virgules, qui seront alors exécutées dans leur ordre, de manière similaire à ORDER BY en SQL.

La méthode de tri par défaut est DESC. Voici quelques exemples pour le paramètre sort.

• published_at - trié par published_at par ordre décroissant
• published_at ASC - trié par published_at par ordre croissant
• is_featured DESC, published_at DESC - les articles à la une en premier, puis triés par heure de publication par ordre décroissant. DESC est optionnel. is_featured, published_at est identique au précédent.

6. Le paramètre keys

Le paramètre keys peut être utilisé pour inclure ou exclure des clés des objets, de manière similaire à GraphQL. Tous les points de terminaison prennent en charge le paramètre keys.

Si vous appelez le point de terminaison /posts, avec keys=id,content, les objets d’article ne contiendront que ces deux clés.

{
    "id": 1000,
    "content": "<p></p>"
}

Utilisez ! au début pour exclure des étiquettes. Par exemple, keys=!content,description exclura content et description de l’objet Post et toutes les autres clés seront incluses.

Disons que vous souhaitez uniquement obtenir l’ID de l’article et l’ID de l’étiquette des articles. Utilisez keys=id,tags.id. Vous obtiendrez des objets comme ceci.

{
    "id": 1000,
    "tags": [
        {
            "id": 2000
        }
    ]
}

Objets

Objet Post

{
    "id": 1000,

    "created_at": 1639655890,
    "updated_at": 1639655890,
    "published_at": 1639665890,

    "is_featured": false,
    "is_page": false,
    "slug": "hello-world",
    "content": "<p></p>",
    "title": "Hello World",
    "description": "This is a hello world page",
    "url": "https://subdomain.hyvorblogs.io/hello-world",
    "featured_image_url": "https://example.com/image.png",
    "canonical_url": null,
    "words": 500,
    "code_head": "",
    "code_foot": "",

    "language": language object,
    "variants": [ variant objects ],

    "tags": [ tag objects ],
    "tags_private": [ tag objects ],
    "authors": [ author objects ]
}

Objet Tag

{
    "id": 2000,
    "created_at": 1639655890,
    "is_private": false,
    "name": "Hello World",
    "description": "Saying hello to the world",
    "slug": "hello-world",
    "url": "https://subdomain.hyvorblogs.io/tag/hello-world",
    "posts_count": 20,
    "code_head": null,
    "code_foot": "<p>some code</p>",

    "language": language object,
    "variants": [ variant objects ],
}

Objet Author

{
    "id": 3000,
    "created_at": 1639655890,
    "slug": "blogger",
    "url": "https://subdomain.hyvorblogs.io/author/blogger",
    "name": "Blogger",
    "picture_url": "https://example.com/image.png",
    "bio": "I am a blogger",
    "website_url": "https://example.com",
    "location": "France",
    "social": social media object,
    "posts_count": 32,

    "language": language object,
    "variants": [ variant objects ],
}

Objet Blog

{
    "subdomain": "alex",
    "name": "My Blog",
    "description": "This is my blog hosted on Hyvor Blogs",
    "logo_url": "https://blog.hyvorblogs.io/media/logo.png",
    "icon_url": "https://blog.hyvorblogs.io/media/icon.png",
    "cover_url": "https://blog.hyvorblogs.io/media/cover.png",
    "url": "https://blog.hyvorblogs.io",
    "social": social media object,
    "nav_header": [
        {
            "name": "Home",
            "url": "/"
        },
        {
            "name": "About",
            "url": "/about"
        }
    ],
    "nav_footer": [
        {
            "name": "Privacy",
            "url": "/privacy"
        }
    ],

    "languages": [ language objects ],

    "code_head": "",
    "code_foot": "",

    "posts_count": 200,

    // the following are blog settings
    // which are used for generating header code, color themes
    // and footer branding
    "seo_indexing": true,
    "color_modes": "light",
    "color_mode_default": "light",

    // for cache busting
    "cache_version_styles": 1,
}

Objet Language

{
    "id": 1000,
    "code": "en",
    "name": "English",
    "is_primary": true,
    "direction": "ltr"
}

Objet Variant

Un objet variant contient les données d’une variante linguistique d’un article, d’une étiquette ou d’un auteur.

{
    "language": {
        "id": 1001,
        "code": "fr",
        "name": "French",
        "is_primary": false,
        "direction": "ltr"
    },
    "url": "https://subdomain.hyvorblogs.io/fr/hello-world"
}

Objet Pagination

Un objet pagination est inclus dans tous les points de terminaison à objets multiples (/posts, /authors, /tags).

{
    "total": 100,
    "pages": 10,
    "limit": 5,
    "page": 1,
    "page_prev": null,
    "page_next": 2,
}

Objet Social Media

{
    "facebook": null,
    "twitter": "https://twitter.com/HyvorBlogs",
    "linkedin": "https://www.linkedin.com/company/30240435",
    "youtube": null,
    "instagram": null,
    "github": "https://github.com/hyvor",
    "tiktok": null
}

Gestion des erreurs

En cas d’erreur, le code de statut HTTP sera un code de statut différent de 200.

Pour les erreurs 4xx, la réponse sera un objet JSON.

{
    "error": "ID is required",
    "error_code": "422"
}

Ces codes HTTP sont possibles :

• 404 Not Found - Ressource non trouvée - 404 peut être retourné dans les points de terminaison à objet unique lorsque l'objet n'est pas trouvé - Assurez-vous que l'ID/slug (et la langue pour les articles) est correct
• 422 Unprocessable Entity - Entrée invalide
  • Vérifiez les paramètres de requête
  • Vous pouvez trouver plus de détails dans la sortie JSON de l’erreur

Les erreurs 5xx signifient qu’un problème est survenu de notre côté. Consultez notre page de statut pour toute interruption de service. Si le problème persiste, contactez-nous.

Pages

Nous n’avons pas de points de terminaison distincts pour récupérer les Pages.

• Pour obtenir une seule page, appelez le point de terminaison /post avec l’ID ou le slug de la page.
• Pour obtenir plusieurs pages, appelez le point de terminaison /posts avec le paramètre ?pages=true.
• /posts/search ne prend pas en charge la recherche de pages.