No, this post is not about the cute Appearance Miku, also known as ApiMiku. Instead, I’m going to tell something about the application programming interfaces (APIs) provided by VocaDB, and most importantly the second version of the API.

As some of you know, VocaDB provides a limited public API for easy programmatic access to some of the site’s main resources. One of the greatest benefits of a custom made site like VocaDB is that it’s able to provide such an easy way for sharing content between similar sites. This means that anything contributed on VocaDB is not limited to just that one site, but can be used by programmers developing other Vocaloid-related sites. Currently the API is being actively used by sites/services such as the Project Diva Wiki and mikumonday’s cytube. VocaDB on the other hand downloads post information from Youtube’s and SoundCloud’s APIs.

The first version of the API (at /api/v1) is based on ASP.NET MVC, which is primarily meant for serving HTML pages. It has been developed ad-hoc, based on requests by programmers who wished to gain access to the site’s resources. Along the way I’ve learned new things about API design (mostly how to really implement the REST pattern), and new tools have been released (most importantly the ASP.NET Web API). So I think it’s time for the first major redesign of the API, upgrading it to use the latest tools and patterns available.

The new API (v2) is based on the aforementioned ASP.NET Web API library, specifically designed for implementing such APIs. This doesn’t have much visible effect on the consumers of the API, except for one thing: Web API uses the “accept” HTTP header to determine content type. In v1 API the content type was determined by the “format” query parameter. By default the API always returned JSON. I’m still debating whether there’s need to allow overriding the content type with that parameter, but by default the content type is now determined by the HTTP header. Other major changes are:

  • Endpoint for the latest version of the API will be just /api/.
  • None of the optional fields (such as artists for an album) are included by default. You need to specify optional fields explicitly.
  • Optional fields are specified with “fields” query parameter, for example /api/albums/1?fields=artists,names,pvs
  • Routes will be changed to better follow the REST conventions. /album/details/1234 will become /albums/1234 and /album/tracks/1234 will become /albums/1234/tracks.

If you have comments or requests regarding the API development, the time to speak is now.

5 thoughts on “VocaDB APIs – preparing for v2”

    1. No, nothing will be reset. Just adding new interfaces, which by the way are there already.

Leave a Reply