API Versioning

[koajs]

API Versioning

[heshiming]

For nginx, the configuration below is pretty much what you have to do to implement versioning

upstream api_v1 {
    server 127.0.0.1:4000;
}

upstream api_v2 {
    server 127.0.0.1:4001;
}

server {
    listen 0.0.0.0:80;
    server_name api.com;

    # pass the request to the node.js server with the correct headers and much more can be added, see nginx config options
    location /v1/ {
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $http_host;
        proxy_set_header X-NginX-Proxy true;

        proxy_pass http://api_v1/;
        proxy_redirect off;
    }

    # pass the request to the node.js server with the correct headers and much more can be added, see nginx config options
    location /v2/ {
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $http_host;
        proxy_set_header X-NginX-Proxy true;

        proxy_pass http://api_v2/;
        proxy_redirect off;
    }
}

On top of this, you'll also need monit to monitor crashes, and upstart to launch. The details can be found here: http://howtonode.org/deploying-node-upstart-monit . All you need is set correct startup parameters so that they serve different ports.

Though simple, the api-boilerplate made good points regarding versioning. That is, you don't handle versioning inside the nodejs app. In the above configuration, you'll have one copy for one version of the nodejs app. They serve /api/something though from nginx, they are rerouted to /v1/api/something or /v2/api/something. It's worth noting that the two versions can have different dependencies, a typical situation during development, without interfering with one another.

[rynz]

Say if the root of my application was running a single node instance that virtualized each koa application within it, eg:

app.use(function *(next) {
  switch (this.host) {
    case 'example.com':
    case 'www.example.com':
      return yield wwwSubdomain.call(this, next);
    case 'bar.example.com':
      return yield barSubdomain.call(this, next);
  }

  return yield next;
});

Should I structure my app as appv1\api\, appv2\api\ etc?

[tj]

Yeah I'd recommend using Nginx (or similar) as well, node isn't great for proxying, and running them all in a single giant app via mounting is doable, but not recommended in production since one failure will bring them all down

[heshiming]

Why would you handle APIs for different domains in the same app? A single clone of the api-boilerplate code handles a single version, with no extra code. As I said versioning is implemented via configurations, not code. Does this answer your question?

[rynz]

Yeah that does. Okay nginx it is, thank you.