VASCAN’s Web Service 0.1

Thursday, 3 October 2013

Today we released a web service for the database of Vascular Plants of Canada (VASCAN).

We did this in response to several requests from users that are not well fulfilled via a web site or via custom downloads. This new capability was several weeks in the making because we took great care to develop a utility that is easy to use, is fast and reliable, and produces easily understood and consumed machine-readable responses. The majority of this time was spent honing and optimizing search, which is used on both the web site and in this new web service. Stay tuned for a future post about how we redesigned search in VASCAN. The documentation for this new web service illustrates what are the expected parameters and what is its output. Except for a rate limit and a generous cap on the number of scientific or vernacular names you can submit in a single request, there are no restrictions on its use.

What is a web service? Why did we do this? What is the point of a web service?

What is a Web Service?

A Web service is a method of communication between two electronic devices over World Wide Web. (source: Wikipedia)

Web services have many specifications, protocols, and frameworks. They may be open or closed source and they have various degrees of documentation or adoption. At its most basic level, a web service accepts a query and then produces a response. It’s the structure of those queries and responses that can vary depending on the protocol. In the absence of good documentation with examples on how to use it, a web service wouldn’t be particularly useful.

What is the VASCAN Web Service?

In short, it’s a URL with a query parameter:

http://data.canadensys.net/vascan/api/0.1/search.json?q=<<something>>

Where <<something>> can be vernacular name, a scientific name, or a VASCAN identifier. You can also use your own local identifier followed by a pipe, |. The response is a bit of JSON, an acronym for JavaScript Object Notation. There are a number of code libraries written in Java, Ruby, PHP, Objective-C among other languages that know what to do with this response.

What is the Point of a Web Service?

We cannot anticipate with certainty everyone’s needs. Although the VASCAN web site is easy to use with plenty of ways to query and download data, it is somewhat limiting for power users or for developers charged with integrating its data into third party applications. You might have cross-referenced your list of plant names with those in VASCAN to detect nomenclatural issues (eg http://dx.doi.org/10.1016/j.palaeo.2013.06.003). You might desire a mechanism to execute real-time scientific name look-ups in your collections management software. You might have tried to synchronize your list with that of VASCAN to keep pace with the edits performed by the tireless botanists who work behind the scenes. Finally, you might have used vascular plant names as the glue to bind ecological data sets in preparation for analyses or to integrate other sources of information such as legislation in web-based products (eg http://www.plantsofcanada.info.gc.ca/). These are merely a handful of the possible use cases for a web service. There are many, many more examples we have not yet dreamt up. Web services are enablers of distributed creativity.

Creating a web service for VASCAN was also a very useful exercise for the Canadensys team. It meant spending time examining how others design their web services like GBIF’s upcoming suite, EOL’s services, or those developed by the Catalogue of Life. Examining what others do led us to several design principles:

Web Service Design Principles

• It must be RESTful by accepting GET and POST requests
• It must return JSON or XML by appending the resource with an extension
• It must have an explicit version number in the URL path that is similar in spirit to semantic versioning
• It must use Darwin Core terms in the response
• It must have few query parameters that accommodate multiple types of values
• It must accept local identifiers and return them in the response

Those are a few of our design principles. The version number in the path is particularly important to you as a consumer of the service and to the Canadensys development team. The biodiversity informatics community has not yet settled on a standard structure for the RESTful web service responses it produces for occurrence or checklist data. Although we would happily present the VASCAN web service response as a straw man standard, it might (and probably will!) change at some point in the future. Nonetheless, we will maintain a period of backward compatibility such that you can be confident that we won’t break your integration of the web service. This is how the Google Maps API is designed. We would do well to learn from the Google Maps team’s successes.

If you have an idea how you might use the VASCAN web service, would like to learn more about how you could use it, or would like to discuss our design principles, we welcome your feedback in the comments below.