Amusez-vous avec l'API du livre relié : une référence rapide

Je suis un utilisateur de longue date de Goodreads, mais j'ai toujours voulu essayer quelque chose de mieux en matière de suivi de mes livres. J'ai donc récemment commencé à utiliser Relié, un concurrent géré par une petite équipe indépendante. Nous n’en sommes qu’à nos débuts et je sais qu’il est difficile de battre quelque chose d’aussi important que Goodreads, mais j’ai bon espoir !

L'un des avantages de Relié est que, contrairement à Goodreads, il dispose d'une API gratuite et vous permet d'interroger toutes les données sur les livres stockés dans Relié. Il peut également être utilisé pour faire pratiquement tout ce que vous pourriez faire vous-même dans l'interface utilisateur du livre relié, comme mettre à jour le statut des livres que vous êtes
lire, ajouter des livres à des listes et plus encore.

Comment j'utilise l'API de Hardcover

En ce moment, j'utilise l'API pour générer la section critique de livre de mon site. J'ai récupéré toutes mes critiques sur Relié et je les stocke dans un fichier JSON. Je parcours ensuite les avis de cette liste et les affiche tous sur la page.

Je ne savais pas trop quoi faire avec les avis très courts, donc pour le moment, j'ai décidé de rendre les avis tels quels sur la page s'ils contiennent moins de 360 ​​caractères, et de créer un lien vers une page séparée si ils sont plus que ça.

J'ai également ajouté une barre de recherche, qui recherchera dans tous mes avis, et j'ai configuré un flou de texte s'il y a des spoilers sur l'avis.

À l'avenir, j'aimerais ajouter un moyen de filtrer par nombre d'étoiles et par genre également.

Premiers pas avec l'API de Hardboard

L'API de Hardcover est également encore en mode d'accès anticipé, et il n'y a pas encore de documentation appropriée, donc dans cet article, je vais passer en revue certaines des requêtes que j'ai trouvées utiles jusqu'à présent. Le serveur Discord de Hardtop est également un endroit idéal pour obtenir des réponses à vos questions.

Vous devrez d'abord accéder à votre page de paramètres et obtenir votre clé API relié. Vous pouvez ensuite tester vos requêtes dans la console GraphQL de Hardboard.

Obtenir tous les livres que vous avez lus

En commençant par une requête GraphQL de base, nous pouvons filtrer en utilisant le status_id pour obtenir une liste des titres de tous les livres que vous avez marqués comme « lus » dans Relié :

{
  me {
    user_books(where: {status_id: {_eq: 3}}) {
      rating
      book {
        title
      }
    }
  }
}

Nous l'avons inclus dans ce que vous pouvez utiliser pour interroger tout ce qui est spécifique à votre utilisateur.

La façon dont fonctionne la valeur status_id est :

• 1 : Un livre « envie de lire »
• 2 : Un livre « en cours de lecture »
• 3 : Un livre « lu »
• 5 : Livre « A n'a pas fini »

Trouver l'auteur d'un livre

Si vous recherchez cached_contributors, vous obtiendrez un tableau contenant une liste de « contributeurs » à un livre. Celui-ci contiendra un ensemble prédéterminé de données, comme le nom, l'identifiant et l'image du contributeur.

{
  me {
    user_books(where: {status_id: {_eq: 3}}) {
      rating
      book {
        title
      }
    }
  }
}

La raison pour laquelle ils sont « contributeurs » et non « auteurs » est qu'il peut également contenir les noms des personnes qui ont traduit le livre. S'il y a plusieurs auteurs, ils figureront également tous dans la liste. Si vous effectuez une requête sur un livre de fiction classique avec un seul auteur, utiliser le premier élément de la liste conviendra généralement.

La version en cache est plus rapide à interroger, mais si vous souhaitez quelque chose de spécifique, vous pouvez également interroger les contributions non mises en cache :

book {
  cached_contributors
}

Obtenir l'URL d'un livre relié

Si vous souhaitez obtenir le lien du livre sur la couverture rigide, vous pouvez rechercher son slug :

book {
  title
    contributions {
      author {
        name
       }
    }
 }

Un slug est la chaîne après le nom de domaine du site Web, par ex. sur emgoto.com/hardcover-book-api, le bit « hardcover-book-api » est le slug.

Donc, une fois que vous aurez obtenu le slug, il vous suffira d'ajouter https://hardcover.app/books/ au début de celui-ci pour créer votre URL de couverture rigide.

Obtenir les balises de genre sur un livre

Le système de balises de genre dans la couverture rigide est généré par l'utilisateur. Vous pouvez interroger les cached_tags, qui vous renverront les balises dans l'ordre du plus balisé au moins.

book {
  slug
}

Une fois que vous avez la liste complète des balises, vous pouvez utiliser cached_tags['Genre'] pour obtenir celles spécifiques au genre.

Si beaucoup de gens ont étiqueté un livre particulier comme fiction, ce sera le premier genre qui apparaîtra dans la liste. Il est intéressant de noter que les gens aiment qualifier leurs livres de fantastique, et donc ce genre apparaît souvent avant l’étiquette de fiction. Les gens aiment tellement étiqueter leurs livres comme fantastiques que les livres de science-fiction comme Dune finissent même avec des étiquettes à la fois de science-fiction et de fantasy.

Si vous envisagez d'utiliser ces données, je vous recommande d'abord de les nettoyer un peu. Par exemple, si le livre contient à la fois de la fantasy et de la science-fiction comme étiquette de genre, utilisez uniquement celle qui vient en premier dans la liste et supprimez l'autre, car elle est plus susceptible d'être exacte.

Ajouter un livre à votre liste « à lire »

Jusqu'à présent, je n'ai abordé que la récupération de données, mais vous pouvez également utiliser l'API de Hardtop pour manipuler des données - bien sûr, vous ne pouvez pas toucher aux choses de quelqu'un d'autre, mais tout ce que vous pouvez faire sur votre propre compte Hardboard est un jeu équitable. .

Si vous disposez de l'identifiant d'un livre, vous pouvez l'ajouter à votre liste « à lire » en définissant son status_id sur 1 :

book {
  cached_tags
}

Obtenir vos critiques de livres

C'est ce que j'utilise pour récupérer toutes les critiques que j'ai écrites dans Relié :

{
  me {
    user_books(where: {status_id: {_eq: 3}}) {
      rating
      book {
        title
      }
    }
  }
}

Presque tous mes livres et critiques sont importés de Goodreads, et je pense que parfois les données sont un peu gâchées lors de l'importation. J'ai trouvé que le trier à la fois par date_added et review_at était plus précis.

J'ai utilisé la valeur review_raw pour obtenir le texte de révision, qui n'inclut aucun formatage comme les nouvelles lignes. Cela signifie malheureusement que si votre avis contient plusieurs paragraphes, l'API les crache sous la forme d'un seul long paragraphe comme celui-ci :

book {
  cached_contributors
}

Avec JavaScript, j'ai contourné ce problème en faisant une regex comme celle-ci :

book {
  title
    contributions {
      author {
        name
       }
    }
 }

S'il y a des points sans espaces après eux, vous pouvez deviner qu'il devrait s'agir d'un nouveau paragraphe et ajouter la double nouvelle ligne nn. Ce qui crée un nouveau paragraphe.

Un autre inconvénient est que les balises spoiler sont également manquantes, vous devrez donc les ajouter manuellement.

Il existe également une valeur review_html, que j'ai pensé être plus utile, mais malheureusement, elle semble toujours nulle pour moi. De même, si vous avez une critique avec des spoilers, il existe une valeur review_has_spoilers, mais pour tous les livres que j'ai importés de Goodreads, cette valeur est fausse, vous ne pourrez donc peut-être pas vous y fier.

Rechercher un livre par titre et/ou auteur

La recherche de livres à couverture rigide est assez précise, mais ils n'en ont pas de version 1-1 dans leur API. Il existe de nombreuses façons d'essayer d'imiter leur comportement de recherche, mais un moyen rapide de commencer serait de rechercher par titre, en utilisant _eq :

book {
  slug
}

J'ai classé la liste des livres par user_read_count, car il est probable que le livre intitulé Dune avec le plus grand nombre de lecteurs soit celui que vous recherchez.

Si vous souhaitez filtrer par titre et auteur, la requête de filtre ressemblera à ceci :

book {
  cached_tags
}

Si vous ne souhaitez pas faire de correspondance exacte de chaîne, vous pouvez utiliser la requête _ilike à la place, qui ne correspond pas aux casses, donc l'utilisation des minuscules fonctionnera toujours :

mutation addBook {
  insert_user_book(object: {book_id: 123, status_id: 1}) {
    id
  }
}

Vous pouvez également utiliser les caractères % comme caractères génériques avec _ilike, vous pouvez donc le faire

{
  me {
    user_books(
      where: { _and: [ 
        {has_review: {_eq: true}},
        {status_id: {_eq: 3 }}
      ]}
      order_by: [
        { date_added: desc },
        { reviewed_at: desc }
      ]
    ) {
      reviewed_at
      date_added
      review_raw
      rating
      book {
        title
      }
    }
  }
}

Qui correspondra à n'importe quel auteur contenant le mot « frank ».

En remarque, puisque la couverture rigide utilise Hasura, la recherche sur Google de « comment faire X dans Hasura » vous indiquera généralement comment effectuer ce genre de requêtes plus compliquées.

Obtenir des livres dans vos listes de livres reliés

En plus des listes standard « je veux lire » et « lire », la couverture rigide dispose également d'une fonction de listes personnalisées distincte. Pour récupérer toutes vos listes et les livres qu'elles contiennent, vous pouvez procéder comme suit :

this is the end of one paragraph.And this is the start of the next

Ajouter un livre à une liste

Si vous souhaitez ajouter un livre à une liste, vous devez d'abord saisir l'identifiant de la liste et l'identifiant du livre. Alors c'est aussi simple que ceci :

{
  me {
    user_books(where: {status_id: {_eq: 3}}) {
      rating
      book {
        title
      }
    }
  }
}

Faire un appel API avec JavaScript

Une fois que vous souhaitez quitter la console GraphQL, vous pouvez effectuer des appels API à l'aide de fetch(). À titre d'exemple très rapide, voici moi qui récupère tous mes avis (je l'ai un peu abrégé) :

book {
  cached_contributors
}

Un conseil de pro en programmation pour faciliter la création d'appels de récupération est si vous :

• Aller à Couverture rigide
• Recherchez graphql dans l'onglet Réseau
• Trouvez-en un qui semble utile et qui renvoie des informations
• Cliquez avec le bouton droit sur l'appel réseau > Copier > Copier comme récupération

Il copiera pour vous un appel de récupération similaire à celui que j'ai collé ci-dessus, que vous pourrez ensuite utiliser dans votre propre code.

Une note sur la limitation des taux

Une fois que vous quittez la console GraphQL et commencez à faire des choses dans un script, vous pouvez rencontrer des erreurs ou des problèmes de limitation de débit si vous essayez de faire trop de choses en même temps.

Par exemple, lors de l'ajout d'un nouveau livre à une liste, je trouve qu'essayer d'en ajouter deux en même temps entraînera une erreur dans l'API, probablement parce qu'elle essaie d'ajouter deux livres à la même position dans la liste.

De même, si vous essayez de passer 100 appels différents pour rechercher un livre en fonction de son titre, certains de ces appels expireront. Si vous les répartissez et en faites un toutes les secondes comme suit, vous ne devriez avoir aucun problème :

book {
  title
    contributions {
      author {
        name
       }
    }
 }

De plus, si vous récupérez l'URL de l'image d'un livre à partir d'une couverture rigide, puis tentez de charger les images de 100 livres en même temps sur votre page, l'API vous limitera et certaines images ne se chargeront pas. . Je recommande de mettre un chargement=lazy dans vos balises d'image comme ceci :

book {
  slug
}

De cette façon, les images ne se chargeront que lorsqu'un utilisateur fera défiler vers le bas pour les voir.

Et c'est tout ! J'ai hâte de voir où ira le livre relié - j'espère que ça se passera bien et que nous aurons enfin un tueur de Goodreads entre nos mains. Si vous souhaitez me suivre sur Relié, j'ai par hasard réussi à attraper le pseudo @emma.

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!