Building an embeddable REST API Console

One of my latest projects is an API to access the beer inventory put online by the Utah DABC.  I’ll save the details of that project for another post, but in the meantime you can check out the code on Github.

After making some decent progress, I started to think about how best to share it with the world.  Having worked with many APIs over the course of my programming life, I realized that the ones I enjoyed the most and achieved the quickest success with had one thing in common: an interactive console.

Twitter was the first example that came to mind.  Their console is powered by Apigee, and in a rare failure of my Google-fu, I came to the conclusion that the Twitter API must also be powered by Apigee and the console feature is reserved for paying customers.  (This assumption turned out to be false.)

It then occurred to me that the WordPress.com REST API had it’s own console, and that the company responsible for it had a good track record of open sourcing their work.  I was able to find this blog post about the original console, and subsequently the Github repository with the source code of the current version.

Much of the code is tied to either the WordPress.com domain or the architecture of the API itself.  I took a “bare minimum” approach to modifying the console for my own purposes; turning the root endpoint into a configuration variable, and creating an “authentication provider” that didn’t actually authenticate.  You can see the changes I made here.

Even with a basic API, the result is beautiful:

 

Restify – Specify API Version in URL

Recently, I started a project to build an API for the Utah DABC‘s online beer inventory.

After researching a few NodeJS REST frameworks, I selected Restify because it’s dead simple to use, supports CORS and versioning out of the box, and has a Redis-based response cache plugin available.

I wanted to specify the API version in the URL, but Restify only natively supports the Accept-Version HTTP header.

This Stack Overflow answer suggested a middleware approach to map a version URL prefix to the Accept-Version header, but it didn’t work correctly for “partial” version paths like v1 and v1.0.

Here’s the version I modified to work as I expected:

// allow path based API versioning
// based on https://stackoverflow.com/a/29706259
server.pre(function (req, res, next) {
	var pieces = req.url.replace(/^\/+/, '').split('/'),
		pathVersion = pieces[0],
		semVersion = semver.valid(pathVersion);

	// only if you want to use this routes:
	// /api/v1/resource
	// /api/v1.0/resource
	// /api/v1.0.0/resource
	if (!semVersion) {
		semVersion = pathVersion.replace(/v(\d{1})\.(\d{1})\.(\d{1})/, '$1.$2.$3');
		semVersion = semVersion.replace(/v(\d{1})\.(\d{1})/, '$1.$2.0');
		semVersion = semVersion.replace(/v(\d{1})/, '$1.0.0');
	}

	if (semver.valid(semVersion) && server.versions.indexOf(semVersion) > -1) {
		req.url = req.url.replace(pathVersion + '/', '');
		req.headers['accept-version'] = semVersion;
	}

	return next();
});

Note: this approach requires node-semver.