Seronok dengan API Buku Kulit Keras: Rujukan pantas

Saya adalah pengguna Goodreads yang lama, tetapi sentiasa mahu mencuba sesuatu yang lebih baik apabila menjejaki buku saya. Jadi saya baru-baru ini mula menggunakan Hardcover, pesaing yang dikendalikan oleh pasukan indie kecil. Ia masih di peringkat awal, dan saya tahu sukar untuk mengalahkan sesuatu yang sebesar Goodreads, tetapi saya berharap!

Salah satu perkara hebat tentang Kulit Keras ialah, tidak seperti Goodreads, ia mempunyai API yang boleh digunakan secara percuma dan membolehkan anda membuat pertanyaan untuk sebarang data pada buku yang disimpan dalam Kulit Keras. Ia juga boleh digunakan untuk melakukan apa sahaja yang anda boleh lakukan sendiri dalam UI Kulit Keras, seperti mengemas kini status buku anda
membaca, menambah buku pada senarai dan banyak lagi.

Bagaimana saya menggunakan API Hardcover

Sekarang saya menggunakan API untuk menjana bahagian ulasan buku tapak saya. Saya mengambil semua ulasan saya daripada Kulit Keras, dan saya menyimpannya dalam fail JSON. Saya kemudian mengulangi ulasan dalam senarai ini dan memaparkan semuanya pada halaman.

Saya tidak terlalu pasti apa yang perlu dilakukan tentang ulasan yang benar-benar pendek, jadi buat masa ini saya telah memutuskan untuk memberikan ulasan sebagaimana adanya pada halaman jika mereka di bawah 360 aksara, dan memautkan ke halaman yang berasingan jika mereka lebih daripada itu.

Saya turut menambah bar carian, yang akan mencari melalui semua ulasan saya dan saya telah menyediakan beberapa pengaburan teks jika terdapat spoiler pada ulasan itu.

Pada masa hadapan saya ingin menambah cara untuk menapis mengikut rating bintang dan mengikut genre juga.

Bermula dengan API Hardcover

API Hardcover juga masih dalam mod akses awal dan belum ada sebarang dokumentasi yang betul, jadi dalam siaran ini saya akan membincangkan beberapa pertanyaan yang saya dapati berguna setakat ini. Pelayan Discord Hardcover juga merupakan tempat yang bagus untuk mendapatkan jawapan kepada soalan anda.

Anda perlu pergi ke halaman tetapan anda terlebih dahulu dan dapatkan kunci API Kulit Keras anda. Kemudian anda boleh menguji pertanyaan anda dalam konsol GraphQL Hardcover.

Mendapatkan semua buku yang telah anda baca

Bermula dengan pertanyaan GraphQL asas, kami boleh menapis menggunakan status_id untuk mendapatkan senarai tajuk semua buku yang telah anda tandai sebagai "baca" dalam Kulit Keras:

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

Kami telah membungkusnya dalam diri saya yang boleh anda gunakan untuk membuat pertanyaan tentang apa-apa sahaja yang khusus untuk pengguna anda.

Cara nilai status_id berfungsi ialah:

• 1: Buku “mahu membaca”
• 2: Buku "sedang membaca"
• 3: Buku "baca"
• 5: Buku “A tak habis”

Mendapatkan pengarang buku

Jika anda mencari cached_contributors, anda akan mendapat tatasusunan yang mengandungi senarai "penyumbang" kepada buku. Ini akan mengandungi set data yang telah ditetapkan, seperti nama, ID dan imej penyumbang.

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

Sebab mereka adalah "penyumbang" dan bukan "pengarang" kerana ia juga boleh mengandungi nama orang yang telah menterjemah buku itu. Jika terdapat berbilang pengarang, mereka juga akan berada dalam senarai. Jika anda menyoal buku fiksyen biasa dengan seorang pengarang, menggunakan item pertama dalam senarai biasanya boleh dilakukan.

Versi cache lebih pantas untuk ditanya, tetapi jika terdapat sesuatu yang khusus yang anda mahukan, anda juga boleh membuat pertanyaan tentang sumbangan bukan cache:

book {
  cached_contributors
}

Mendapatkan URL Kulit Keras buku

Jika anda ingin mendapatkan pautan buku pada Kulit Keras, anda boleh bertanya untuk slugnya:

book {
  title
    contributions {
      author {
        name
       }
    }
 }

Slug ialah rentetan selepas nama domain tapak web, mis. pada emgoto.com/hardcover-book-api, bit "hardcover-book-api" ialah slug.

Jadi sebaik sahaja anda mendapat slug, anda hanya perlu menambah https://hardcover.app/books/ pada permulaannya untuk mencipta URL Hardcover anda.

Mendapatkan tag genre pada buku

Sistem tag genre dalam Kulit Keras dijana pengguna. Anda boleh membuat pertanyaan pada cached_tags, yang akan mengembalikan teg kepada anda mengikut tertib daripada yang paling banyak ditag kepada yang paling sedikit.

book {
  slug
}

Setelah anda mempunyai senarai penuh teg, anda boleh menggunakan cached_tags['Genre'] untuk mendapatkan yang khusus genre.

Jika ramai orang telah menandakan buku tertentu sebagai fiksyen, itu akan menjadi genre pertama yang muncul dalam senarai. Menariknya orang suka menandai buku mereka sebagai fantasi, jadi genre ini sering muncul sebelum tag fiksyen. Orang ramai suka menandai buku mereka sebagai fantasi, sehinggakan buku sci-fi seperti Dune malah mempunyai teg sci-fi dan fantasi juga.

Jika anda akan menggunakan data ini, saya syorkan melakukan sedikit pembersihan padanya terlebih dahulu. Contohnya, jika buku itu mempunyai kedua-dua fantasi dan sci-fi sebagai teg genre, hanya gunakan yang didahulukan dalam senarai dan buang yang satu lagi, kerana itu lebih mungkin tepat.

Menambahkan buku pada senarai "untuk dibaca" anda

Setakat ini saya hanya menyentuh tentang mengambil data, tetapi anda juga boleh menggunakan API Hardcover untuk memanipulasi data - sudah tentu anda tidak boleh menyentuh perkara orang lain, tetapi apa sahaja yang anda boleh lakukan pada akaun Hardcover anda sendiri adalah permainan yang adil .

Jika anda mempunyai ID buku, anda boleh menambahkannya pada senarai “untuk membaca” anda dengan menetapkan status_idnya kepada 1:

book {
  cached_tags
}

Mendapat ulasan buku anda

Inilah yang saya gunakan untuk mengambil semua ulasan yang telah saya tulis dalam Kulit Keras:

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

Hampir semua buku dan ulasan saya diimport daripada Goodreads, dan saya fikir kadangkala data menjadi kucar-kacir dalam import. Saya mendapati bahawa mengisih mengikut tarikh_tambah dan disemak_di adalah lebih tepat.

Saya menggunakan nilai review_raw untuk mendapatkan teks ulasan, yang tidak termasuk sebarang pemformatan seperti baris baharu. Malangnya, ini bermakna jika anda mempunyai berbilang perenggan dalam ulasan anda, API mengeluarkan semuanya sebagai satu perenggan panjang seperti ini:

book {
  cached_contributors
}

Dengan JavaScript, saya mengatasinya dengan melakukan regex seperti berikut:

book {
  title
    contributions {
      author {
        name
       }
    }
 }

Jika terdapat sebarang titik tanpa ruang selepasnya, anda boleh membuat tekaan bahawa ini sepatutnya perenggan baharu dan tambahkan dua baris baharu nn. Yang mencipta perenggan baharu.

Keburukan lain ialah tag spoiler juga tiada, jadi anda perlu menambahnya secara manual.

Terdapat juga nilai review_html, yang saya fikir mungkin lebih berguna, tetapi malangnya nilai itu selalu menjadi batal bagi saya. Begitu juga, jika anda mempunyai ulasan dengan spoiler, terdapat nilai ulasan_mempunyai_spoiler, tetapi untuk semua buku yang saya import daripada Goodreads, nilai ini adalah palsu jadi anda mungkin tidak boleh bergantung padanya.

Mencari buku mengikut tajuk dan/atau pengarang

Carian buku kulit keras agak tepat, tetapi mereka tidak mempunyai versi 1-1 ini dalam API mereka. Terdapat banyak cara anda boleh mencuba dan meniru gelagat carian mereka, tetapi cara cepat untuk bermula adalah dengan mencari pada tajuk, menggunakan _eq:

book {
  slug
}

Saya memesan senarai buku mengikut users_read_count, kerana kemungkinan buku yang dipanggil Dune dengan bilangan pembaca tertinggi akan menjadi Dune yang anda cari.

Jika anda ingin menapis mengikut tajuk dan pengarang, pertanyaan penapis akan kelihatan seperti ini:

book {
  cached_tags
}

Jika anda tidak mahu melakukan padanan rentetan yang tepat, anda boleh menggunakan pertanyaan _ilike sebaliknya, yang tidak sepadan pada kes, jadi menggunakan huruf kecil masih berfungsi:

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

Anda juga boleh menggunakan % aksara sebagai kad bebas dengan _ilike, jadi anda boleh melakukannya

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

Yang akan sepadan dengan mana-mana pengarang yang mengandungi perkataan "terus terang".

Sebagai nota sampingan, memandangkan Kulit Keras menggunakan Hasura, Googling untuk "cara melakukan X dalam Hasura" biasanya akan memaparkan cara anda boleh melakukan pertanyaan yang lebih rumit ini.

Mendapatkan buku dalam Senarai Kulit Keras anda

Serta senarai standard "mahu membaca" dan "membaca", Kulit Keras juga mempunyai ciri senarai tersuai yang berasingan. Untuk mengambil semua senarai anda dan buku di dalamnya, anda boleh melakukan perkara berikut:

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

Menambah buku pada senarai

Jika anda ingin menambahkan buku pada senarai, mula-mula anda perlu mengambil ID senarai dan ID buku itu. Kemudian ia mudah seperti berikut:

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

Membuat panggilan API dengan JavaScript

Sebaik sahaja anda mahu keluar dari konsol GraphQL, anda boleh membuat panggilan API menggunakan fetch(). Sebagai contoh yang sangat cepat, inilah saya mengambil semua ulasan saya (saya telah meringkaskannya sedikit):

book {
  cached_contributors
}

Petua pro pengaturcaraan yang perlu saya buat untuk membina panggilan pengambilan adalah lebih mudah adalah jika anda:

• Pergi ke Kulit Keras
• Cari graphql dalam tab Rangkaian
• Cari yang kelihatan berguna dan mengembalikan maklumat
• Klik kanan panggilan rangkaian > Salin > Salin sebagai ambil

Ia akan menyalin untuk anda panggilan ambil yang serupa dengan panggilan yang saya tampalkan di atas, yang kemudiannya boleh anda gunakan dalam kod anda sendiri.

Nota mengenai pengehadan kadar

Sebaik sahaja anda keluar dari konsol GraphQL dan mula melakukan perkara dalam skrip, anda mungkin menghadapi ralat atau isu mengehadkan kadar jika anda mencuba dan melakukan terlalu banyak perkara pada masa yang sama.

Sebagai contoh, apabila menambah buku baharu pada senarai, saya mendapati bahawa cuba menambah dua pada masa yang sama akan ralat dalam API, mungkin kerana ia cuba menambah dua buku pada kedudukan yang sama dalam senarai.

Begitu juga, jika anda cuba membuat 100 panggilan berbeza untuk mencari buku berdasarkan tajuknya, beberapa panggilan ini akan tamat masa. Jika anda menyebarkannya dan melakukan satu setiap saat seperti berikut, maka anda tidak sepatutnya menghadapi sebarang masalah:

book {
  title
    contributions {
      author {
        name
       }
    }
 }

Selain itu, jika anda mengambil URL imej buku daripada Kulit Keras, dan kemudian cuba memuatkan imej 100 buku pada masa yang sama pada halaman anda, API akan menilai menghadkan anda dan sesetengah imej tidak akan dimuatkan . Saya syorkan meletakkan loading=lazy dalam teg imej anda seperti:

book {
  slug
}

Dengan cara ini, imej hanya akan dimuatkan apabila pengguna menatal ke bawah untuk melihatnya.

Dan itu sahaja! Saya berminat untuk melihat ke mana Hardcover seterusnya - Saya berharap ia berfungsi dengan baik, dan akhirnya kami mempunyai pembunuh Goodreads di tangan kami. Jika anda ingin mengikuti saya di Kulit Keras, nasib baik saya telah berjaya merampas pemegang @emma.

Atas ialah kandungan terperinci Seronok dengan API Buku Kulit Keras: Rujukan pantas. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!