Spaß mit der Hardcover-Buch-API: Eine kurze Referenz

Ich bin ein langjähriger Goodreads-Benutzer, wollte aber schon immer etwas Besseres ausprobieren, wenn es darum geht, meine Bücher zu verfolgen. Deshalb habe ich vor kurzem damit begonnen, Hardcover zu verwenden, einen Konkurrenten, der von einem kleinen Indie-Team betrieben wird. Es steckt noch in den Kinderschuhen und ich weiß, dass es schwer ist, etwas so Großes wie Goodreads zu schlagen, aber ich bin zuversichtlich!

Eines der großartigen Dinge an Hardcover ist, dass es im Gegensatz zu Goodreads über eine API verfügt, die kostenlos genutzt werden kann und es Ihnen ermöglicht, alle Daten zu den Büchern abzufragen, die in Hardcover gespeichert sind. Es kann auch für praktisch alles verwendet werden, was Sie auch in der Hardcover-Benutzeroberfläche selbst tun könnten, z. B. um den Status der Bücher zu aktualisieren, die Sie lesen
Lesen, Bücher zu Listen hinzufügen und mehr.

Wie ich die API von Hardcover verwende

Im Moment verwende ich die API, um den Buchrezensionsbereich meiner Website zu generieren. Ich habe alle meine Rezensionen von Hardcover abgerufen und speichere sie in einer JSON-Datei. Anschließend gehe ich die Bewertungen in dieser Liste durch und rendere sie alle auf der Seite.

Ich war mir nicht ganz sicher, was ich mit wirklich kurzen Rezensionen machen sollte, daher habe ich mich vorerst dafür entschieden, die Rezensionen unverändert auf der Seite darzustellen, wenn sie weniger als 360 Zeichen lang sind, und ggf. auf eine separate Seite zu verlinken Sie sind mehr als das.

Ich habe außerdem eine Suchleiste hinzugefügt, die alle meine Rezensionen durchsucht, und ich habe eine Textunschärfe eingerichtet, wenn die Rezension Spoiler enthält.

In Zukunft möchte ich eine Möglichkeit hinzufügen, nach Sternebewertung und auch nach Genre zu filtern.

Erste Schritte mit der API von Hardcover

Die API von Hardcover befindet sich ebenfalls noch im Early-Access-Modus und es gibt noch keine ordnungsgemäße Dokumentation. Daher werde ich in diesem Beitrag einige der Abfragen durchgehen, die ich bisher nützlich fand. Der Discord-Server von Hardcover ist auch ein großartiger Ort, um Antworten auf Ihre Fragen zu erhalten.

Sie müssen zunächst zu Ihrer Einstellungsseite gehen und Ihren Hardcover-API-Schlüssel erhalten. Anschließend können Sie Ihre Abfragen in der GraphQL-Konsole von Hardcover testen.

Holen Sie sich alle Bücher, die Sie gelesen haben

Ausgehend von einer einfachen GraphQL-Abfrage können wir anhand der status_id filtern, um eine Liste der Titel aller Bücher zu erhalten, die Sie in Hardcover als „gelesen“ markiert haben:

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

Wir haben es in mich gepackt, mit dem Sie alles abfragen können, was für Ihren Benutzer spezifisch ist.

Der status_id-Wert funktioniert wie folgt:

• 1: Ein Buch, das ich lesen möchte
• 2: Ein „aktuell gelesenes“ Buch
• 3: Ein „gelesenes“ Buch
• 5: „A wurde nicht fertiggestellt“-Buch

Den Autor eines Buches ermitteln

Wenn Sie nach „cached_contributors“ suchen, erhalten Sie ein Array mit einer Liste von „Mitwirkenden“ an einem Buch. Dies enthält einen vorgegebenen Datensatz, wie den Namen, die ID und das Bild des Mitwirkenden.

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

Der Grund dafür, dass sie „Mitwirkende“ und nicht „Autoren“ sind, liegt darin, dass es auch die Namen von Personen enthalten kann, die das Buch übersetzt haben. Wenn es mehrere Autoren gibt, werden diese auch alle in der Liste aufgeführt. Wenn Sie nach einem regulären Belletristikbuch mit einem Autor suchen, ist die Verwendung des ersten Elements in der Liste normalerweise in Ordnung.

Die zwischengespeicherte Version lässt sich schneller abfragen, aber wenn Sie etwas Bestimmtes wollten, können Sie auch die nicht zwischengespeicherten Beiträge abfragen:

book {
  cached_contributors
}

Abrufen der Hardcover-URL eines Buchs

Wenn Sie den Link des Buchs auf Hardcover erhalten möchten, können Sie nach dem Slug fragen:

book {
  title
    contributions {
      author {
        name
       }
    }
 }

Ein Slug ist die Zeichenfolge nach dem Domainnamen der Website, z. B. Auf emgoto.com/hardcover-book-api ist das „hardcover-book-api“-Bit der Schlüssel.

Sobald Sie also den Slug erhalten haben, müssen Sie nur noch https://hardcover.app/books/ am Anfang voranstellen, um Ihre Hardcover-URL zu erstellen.

Ermitteln der Genre-Tags für ein Buch

Das Genre-Tag-System in Hardcover ist benutzergeneriert. Sie können die zwischengespeicherten_Tags abfragen, wodurch Sie die Tags in der Reihenfolge von den meisten bis zu den am wenigsten getaggten Tags erhalten.

book {
  slug
}

Sobald Sie die vollständige Liste der Tags haben, können Sie „cached_tags['Genre']“ verwenden, um die genrespezifischen Tags abzurufen.

Wenn viele Leute ein bestimmtes Buch als Belletristik markiert haben, wird dieses Genre als erstes in der Liste angezeigt. Interessanterweise kennzeichnen die Leute ihre Bücher gerne als Fantasy-Bücher, weshalb dieses Genre oft vor dem Belletristik-Tag auftaucht. Die Leute lieben es so sehr, ihre Bücher als Fantasy zu kennzeichnen, dass Science-Fiction-Bücher wie Dune am Ende sogar sowohl Science-Fiction- als auch Fantasy-Tags erhalten.

Wenn Sie diese Daten verwenden möchten, empfehle ich, sie zunächst ein wenig zu bereinigen. Wenn das Buch beispielsweise sowohl Fantasy als auch Science-Fiction als Genre-Tag enthält, verwenden Sie nur dasjenige, das in der Liste an erster Stelle steht, und verwerfen Sie das andere, da dieses mit größerer Wahrscheinlichkeit zutreffender ist.

Ein Buch zu Ihrer Leseliste hinzufügen

Bisher habe ich nur das Abrufen von Daten angesprochen, aber Sie können auch die API von Hardcover verwenden, um Daten zu manipulieren – natürlich können Sie die Dinge anderer nicht anfassen, aber alles, was Sie auf Ihrem eigenen Hardcover-Konto tun könnten, ist Freiwild .

Wenn Sie die ID eines Buchs haben, können Sie es zu Ihrer „Zu lesen“-Liste hinzufügen, indem Sie dessen Status_ID auf 1 setzen:

book {
  cached_tags
}

Holen Sie sich Ihre Buchrezensionen

Hiermit rufe ich alle Rezensionen ab, die ich im Hardcover-Format geschrieben habe:

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

Fast alle meine Bücher und Rezensionen werden von Goodreads importiert, und ich denke, dass die Daten beim Import manchmal etwas durcheinander geraten. Ich fand, dass die Sortierung nach „Datum_hinzugefügt“ und „Überprüft_at“ genauer war.

Ich habe den Wert „review_raw“ verwendet, um den Rezensionstext abzurufen, der keine Formatierungen wie Zeilenumbrüche enthält. Das bedeutet leider, dass die API bei mehreren Absätzen in Ihrer Rezension alles als einen langen Absatz wie diesen ausgibt:

book {
  cached_contributors
}

Mit JavaScript habe ich dies umgangen, indem ich einen regulären Ausdruck wie den folgenden erstellt habe:

book {
  title
    contributions {
      author {
        name
       }
    }
 }

Wenn es Punkte ohne Leerzeichen gibt, können Sie davon ausgehen, dass es sich um einen neuen Absatz handelt, und den doppelten Zeilenumbruch nn hinzufügen. Dadurch wird ein neuer Absatz erstellt.

Ein weiterer Nachteil ist, dass auch Spoiler-Tags fehlen, sodass Sie diese manuell hinzufügen müssen.

Es gibt auch einen review_html-Wert, der meiner Meinung nach nützlicher sein könnte, aber leider scheint er für mich immer null zu sein. Wenn Sie eine Rezension mit Spoilern haben, gibt es ebenfalls einen Wert für „review_has_spoilers“, aber für alle Bücher, die ich aus Goodreads importiert habe, ist dieser Wert falsch, sodass Sie sich möglicherweise nicht darauf verlassen können.

Suche nach einem Buch nach Titel und/oder Autor

Die Buchsuche von Hardcover ist ziemlich genau, aber sie haben keine 1:1-Version davon in ihrer API. Es gibt viele Möglichkeiten, ihr Suchverhalten nachzuahmen, aber ein schneller Einstieg wäre die Suche nach dem Titel mit _eq:

book {
  slug
}

Ich habe die Liste der Bücher nach „users_read_count“ geordnet, da die Wahrscheinlichkeit groß ist, dass das Buch namens „Dune“ mit der höchsten Anzahl an Lesern das „Dune“ ist, nach dem Sie suchen.

Wenn Sie nach Titel und Autor filtern möchten, sieht die Filterabfrage folgendermaßen aus:

book {
  cached_tags
}

Wenn Sie keinen exakten String-Abgleich durchführen möchten, können Sie stattdessen die _ilike-Abfrage verwenden, die nicht auf Groß- und Kleinschreibung zutrifft, sodass die Verwendung von Kleinbuchstaben weiterhin funktioniert:

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

Sie können auch %-Zeichen als Platzhalter mit _ilike verwenden, also ist das möglich

{
  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
      }
    }
  }
}

Das passt zu jedem Autor, der das Wort „Frank“ enthält.

Nebenbei bemerkt, da Hardcover Hasura verwendet, wird das Googeln nach „Wie macht man

Erhalten Sie Bücher in Ihre Hardcover-Listen

Neben den standardmäßigen „Willst du lesen“- und „Lesen“-Listen verfügt Hardcover auch über eine separate benutzerdefinierte Listenfunktion. Um alle Ihre Listen und die darin enthaltenen Bücher abzurufen, können Sie Folgendes tun:

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

Ein Buch zu einer Liste hinzufügen

Wenn Sie ein Buch zu einer Liste hinzufügen möchten, müssen Sie zunächst die Listen-ID und die Buch-ID abrufen. Dann geht es ganz einfach wie folgt:

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

Einen API-Aufruf mit JavaScript durchführen

Sobald Sie die GraphQL-Konsole verlassen möchten, können Sie API-Aufrufe mit fetch() durchführen. Als wirklich schnelles Beispiel rufe ich hier alle meine Rezensionen auf (ich habe sie etwas gekürzt):

book {
  cached_contributors
}

Ein Programmier-Profi-Tipp, den ich brauche, um das Erstellen von Abrufaufrufen zu vereinfachen, ist, wenn Sie:

• Gehe zu Hardcover
• Suchen Sie auf der Registerkarte „Netzwerk“ nach graphql
• Finden Sie eines, das nützlich aussieht und Informationen zurückgibt
• Rechtsklick auf den Netzwerkanruf > Kopieren > Als Abruf kopieren

Es wird ein Abrufaufruf ähnlich dem, den ich oben eingefügt habe, für Sie kopiert, den Sie dann in Ihrem eigenen Code verwenden können.

Ein Hinweis zur Ratenbegrenzung

Sobald Sie die GraphQL-Konsole verlassen und anfangen, Dinge in einem Skript zu tun, kann es zu Fehlern oder Problemen mit der Ratenbegrenzung kommen, wenn Sie versuchen, zu viele Dinge gleichzeitig zu tun.

Wenn ich beispielsweise ein neues Buch zu einer Liste hinzufüge, stelle ich fest, dass der Versuch, zwei Bücher gleichzeitig hinzuzufügen, zu einem Fehler in der API führt, wahrscheinlich weil versucht wird, zwei Bücher an derselben Position in der Liste hinzuzufügen.

Wenn Sie 100 verschiedene Anrufe tätigen, um anhand des Titels nach einem Buch zu suchen, kommt es bei einigen dieser Anrufe ebenfalls zu Zeitüberschreitungen. Wenn Sie sie verteilen und jede Sekunde eine wie folgt ausführen, sollten Sie keine Probleme haben:

book {
  title
    contributions {
      author {
        name
       }
    }
 }

Wenn Sie außerdem die Bild-URL eines Buchs von Hardcover abgerufen und dann versucht haben, die Bilder von 100 Büchern gleichzeitig auf Ihre Seite zu laden, wird die API die Geschwindigkeit begrenzen und einige der Bilder werden nicht geladen . Ich empfehle, in Ihre Bild-Tags „loading=lazy“ einzufügen, etwa so:

book {
  slug
}

Auf diese Weise werden die Bilder nur geladen, wenn ein Benutzer nach unten scrollt, um sie anzuzeigen.

Und das ist es! Ich bin gespannt, wohin das Hardcover als nächstes geht – ich hoffe, dass es gut ankommt und wir endlich einen Goodreads-Killer in unseren Händen haben. Wenn Sie mir auf Hardcover folgen möchten, habe ich es zufällig geschafft, den @emma-Griff zu ergattern.

Das obige ist der detaillierte Inhalt vonSpaß mit der Hardcover-Buch-API: Eine kurze Referenz. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!