GSoC 2019: JSON Web API for BookBrainz

The time has come to wrap up the very productive and learning summer of the last 3 months as a GSoC student with MetaBrainz.

Hello Everyone!!

I am Akhilesh Kumar, a recent graduate from the National Institute of Technology, Hamirpur, India. I have been working on BookBrainz for MetaBrainz Foundation Inc. as a participant in the Google Summer of Code ’19. It has been an amazing experience and I’ve learned a lot over the summer. I was mentored by Nicolas Pelletier (Mr_Monkey on IRC) during this period. This post summarizes my contributions to the project and the experiences that I had throughout the summer.

I started contributing code to BookBrainz in February 2018 and before GSoC I mainly worked on adding a statistics page in PR #184 and PR #191, adding initial relationship when creating entity in PR #247, improved the flow of contributing in PR #248, adding a Work table on Edition pages in PR #250 and other minor changes of existing features and many bug fixes.

For Google Summer of Code 2019, I made a proposal, that was aimed to design and implement a JSON API to programmatically query the BookBrainz database along with unit testing and documentation of both the code and the API. The API will use the current BookBrainz ORM, bookbrainz-data-js, to access the database.

Summary of my contributions to the project during the summer

API setup

First I set up the API section by writing the code related to the API only and common section for common code of API and the web-server. The API has own app.js file which is configured according to API requirements. Common utility functions have been moved to the common section. I modified some scripts in package.json to run the API and API tests. Code related to this setup is found in PR #293.

Lookup Request Endpoints

This was the first section of API endpoints to get basic information of entity by using BBID of that entity. The implementation of these endpoints is also in PR #293. For this section of the proposal, unit tests are written and documentation of code, as well as API, has been finished. After many phases of review, this PR has been merged into master and running the testing server.

Browse Request Endpoints

These endpoints will be used to get the entity or list of entities by using the BBID of the directly linked entity. The endpoint has almost been implemented with some unit tests and endpoint documentation. The implementation of these endpoints can be seen in PR #297. This PR is also at the almost final phase. Many phases of review have been done. This will ready to merge after some little changes.

Search Request Endpoint

This endpoint will be used to search entities from the database by the alias/name of the entity. Filter options are also available to make entity search easy. Implementation of this endpoint has been completed with tests and documentation—details can be seen in PR #299. This PR will be ready to merge after a final review. No more changes are required by mentor on the discussion at this PR.

Rate Limiter

A basic rate limiter module has been implemented by using the express-slow-down package. This will prevent the server from DOS attacks and control the request traffic by tracking API requests based on the IP address of clients. Implementation details can be seen in PR #300. This PR has been reviewed by the mentor and will merge after some configuration discussion on the community forum.

API Documentation

Documentation of API has been completed along with the endpoint implementation. For the documentation, the swagger-jsdoc and swagger-ui-express packages are used. These packages provide flexibility to write the endpoint documentation just above the endpoint code as a comment. Documentation of implemented endpoints can be seen here and you can try those endpoints to fetch real data from the documentation page. This is a fantastic feature provided by swagger.


This summer was awesome for me. I learned a lot of new things and techniques for writing better code as well as got to brush up on my existing skills and interact with the completely awesome MetaBrainz community. A special thanks to my mentor Nicolas Pelletier for always being patient and helping me out whenever I felt stuck. My sincerest gratitude to Google for running such a great and extremely inclusive program which allows students from all over the world to avail themselves of such an opportunity. I’m really looking forward to keep contributing to BookBrainz. Now I am very excited to meet the MetaBrainz community on MetaBrainz summit 2019. Thank you, Robert Kaye, for giving me such an opportunity. I would also thank Param Singh (iliekcomputers on IRC) for suggesting MetaBrainz Organization and encouraging me to start open-source contributions.

Thank you MetaBrainz community for your continuous guidance and support!

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.