JSON API: Books

Bookshelves and book metadata via the API.

Get bookshelves

Returns JSON Feed that also includes a books_count field in _microblog with the number of books in a bookshelf.

GET /books/bookshelves
Authorization: Bearer 123456789
{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "Micro.blog - Bookshelves",
  "home_page_url": "https://micro.blog/",
  "feed_url": "https://micro.blog/books/bookshelves",
  "_microblog": {
    "about": "https://micro.blog/about/api"
  },
  "items": [
    {
      "id": 22,
      "title": "Currently reading",
      "content_text": "",
      "url": "https://micro.blog/account/bookshelves/22",
      "date_published": "2021-06-16T21:34:20+00:00",
      "_microblog": {
        "books_count": 5
      }
    },
    {
      "id": 23,
      "title": "Want to read",
      "content_text": "",
      "url": "https://micro.blog/account/bookshelves/23",
      "date_published": "2021-06-16T21:34:20+00:00",
      "_microblog": {
        "books_count": 10
      }
    }
  ]
}

Get books in a bookshelf

Pass the id from /books/bookshelves. Returns JSON Feed with each item representing a book. The isbn is in the _microblog namespace.

GET /books/bookshelves/123
Authorization: Bearer 123456789
{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "Micro.blog - Currently reading",
  "home_page_url": "https://micro.blog/",
  "feed_url": "https://micro.blog/books/bookshelves/25",
  "_microblog": {
    "about": "https://micro.blog/about/api"
  },
  "items": [
    {
      "id": 79,
      "title": "Project Hail Mary",
      "content_text": "",
      "url": "https://micro.blog/books/9780593395561",
      "image": "https://images.isbndb.com/covers/55/61/9780593395561.jpg",
      "date_published": "2021-06-16T21:38:46+00:00",
      "authors": [
        {
          "name": "Andy Weir"
        }
      ],
      "_microblog": {
        "isbn": "9780593395561"
      }
    }
  ]
}

Add a new bookshelf

Every user will automatically have the default bookshelves like “Currently reading”. Accepts a single form-encoded parameter: name

POST /books/bookshelves
Authorization: Bearer 123456789

Rename a new bookshelf

The bookshelf id goes in the URL. Accepts a single form-encoded parameter: name

POST /books/bookshelves/123
Authorization: Bearer 123456789

Add a new book

Accepts form-encoded parameters:

  • title
  • author
  • isbn
  • cover_url
  • bookshelf_id

Where possible, Micro.blog will try to find the cover art for you based on ISBN and include that in subsequent bookshelf JSON responses.

POST /books
Authorization: Bearer 123456789

Move a book into a different bookshelf

Accepts form-encoded parameters:

  • book_id

If you already have a book_id, use this to copy or move it to a different bookshelf (specific in the URL).

POST /books/bookshelves/123/assign
Authorization: Bearer 123456789

Remove a book from a bookshelf

The bookshelf and book IDs go in the URL.

DELETE /books/bookshelves/123/remove/79
Authorization: Bearer 123456789

Getting reading goals

Micro.blog can keep track of reading goals for each year. For example, you may want to try to read 15 books this year. When you blog about a book you’ve read, Micro.blog will update the progress of your goal.

GET /books/goals
Authorization: Bearer 123456789

Get books list progress toward a goal

GET /books/goals/123
Authorization: Bearer 123456789

Update reading goal

Update the value of a reading goal based on the id returned from the goals JSON. You can update just the value or the progress field (how many books you’ve read toward the goal, which is automatically tracked by Micro.blog).

POST /books/goals/123
Authorization: Bearer 123456789

Accepts form-encoded parameters:

  • value
  • progress (optionally, usually left off)

Searching for books

Micro.blog can’t provide an API for searching books. You will need to integrate with another book search API such as Open Library, ISBNdb, Google Books, or Amazon.