Find me around

  • Facebook
  • Twitter
  • Check me out in Pinterest!
  • linkedin-logo-grey
  • The Couch Developer channel
  • My Github profile
  • Stackoverflow profile
  • Email me!
  • Fernando Doglio

Version 1.5 of VaticanJs is out!



As part of my recent brush with version 1.4 of VaticanJS, I decided to keep working on it, so I picked a couple of tickets I had laying around on the project's Github page and started to code away.

From them, the following features / enhancements came out:


+ Event-based notification for things like: db ready, handlers parsed, server ready, etc.

+ Automatic endpoint versioning

+ Automatic support for Options requests.


Let's get into more details for each one:


On ready events

One issue I found during my tests, was that VaticanJS was not immediately ready to start processing requests since it required a few microseconds to finalize parsing all of the handlers. Remember that since annotations aren't part of JavaScript, the framework needs to handle them on its own.

So now, after all handlers have been successfully parsed, a "READY" event will be triggered, and you can register your code to it by simply doing:


const Vatican = require("vatican");
Vatican.on('READY', () => {
///your code here...
});

In fact, you'll also get a whole set of events from now on:

+ READY: This is the one from above, triggered after VaticanJS is done parsing your handler files.

+ DB-READY: This one is triggered whenever the connection to the database is ready

+ SERVER-READY: Once the HTTP server is created, this event will be triggered

+ INIT-ERROR: If there is any problem parsing your handler files, you'll get this event triggered, with the error as a parameter

+ DB-ERROR: Same but for the db connection



Options request support

Now, OPTIONS support, will work correctly with your endpoints. By default your API will return a list of accepted methods, taken from whatever you configured with the annotations.

You don't have to do anything for this to work, it'll work right out of the box.


Endpoint Versioning

This one's a bit tricky. The idea is to have it be as seamless as possible, but at the same time as powerful as possible, so here is what I came up with:


+ VaticanJS supports URL versioning (by prefixing your path with the version) and Header versioning using the Accept header and a custom MimeType

+ You can specify one or multiple versions for your endpoints on your annotations

+ You can customize the format your version takes on your URL and Headers, while keep using SemVer on your annotations at the same time (i.e you set 1.1.0 on your annotation but show "latest/your/path" on your URL).


This all works out of the configuration parameters passed when you instantiate VaticanJS. The parameters are:

+ versioning: (optional, by default there is no versioning enabled) Object, contains all the versioning parameters.

+ versioning.strategy: String, either "url or "header"

+ versioning.matching: (optional) Function, used to match a custom string to your endpoint's SemVer version.


So, by doing something like:


new Vatican({ versioning: { strategy: "url", matching: (urlV, endpointV) { let v = urlV.substring(1); return +v == +endpointV.split(".")[0]; } } })

Will match URLs like "/v1/your/path" to your annotations, like: @endpoint (url: /your/path method: get versions: [1.1.0])


And you can even use the same config, but with the "header" strategy, and send an Accept header with the following value: accept/vnd.vatican-version.v1+json


That's it for this explanation, if you want to know more, you can check the versioning definition on Github or check out the full documentation for VaticanJS here in this site.

Let me know if you have any questions or comments down below.


Thanks for reading!


  • Black Twitter Icon