Create api versions about feathers

[ekryski]

Yep good call. I'm thinking two options:

• We default to all endpoints having a version (starting with 1), which you can overwrite
• We do as you suggest which would force people to always define custom service wrappers when they want to version things

There may be another way to have this configurable without forcing custom service wrappers. I'll have to look into this one.

[daffl]

I am not so sure if versioned URIs are really REST-ful (see http://stackoverflow.com/questions/972226/how-to-version-rest-uris). You should do versioning via custom content types (e.g. myapp/json+v1) and content negotiation. For versioned URIs you can always do

app.use('/v1/todos', oldTodoService)
   .use('/v2/todos', todoService)

It would be great to make the default REST provider more HTTP compliant and RESTful in this aspect though (e.g. by adding custom content types).

[ekryski]

I don't thinking versioning really breaks REST but I get what @daffl is saying. Let's discuss this a bit.

[norman784]

A clean, easy and with backward compatibility solution will be just check if version is defined, if not just do as now.

With this solution you will not break existing projects, because if someone is using it in production will have troubles updating the lib.

And this is just a suggestion maybe some people like to naming their versions in other ways, but I found this one the most easy to understand, a good lecture of best practices are API FAÇADE PATTERN and
WEB API DESIGN

The main reason to versioning its to evolve your api without worrying to break your current production apps thats are consuming it....

[ekryski]

I agree we do need to support versioning in some fashion but after thinking about it a bit more I'm inclined to go with what @daffl posted above. You can always do:

app.use('/v1/todos', oldTodoService)
     .use('/v2/todos', todoService)

It's kind of crappy if you want to version all of your resources but it's not really any different than what you had suggested. It'll be much more apparent to someone else reading your code as to how the resources are versioned instead of having look for the version buried in the resource handler.

[daffl]

I don't think it would be even that crappy. This is where Uberproto can come in handy:

var TodoService = Proto.extend({
  get: function(id, params, callback) {
    callback(null, {
      id: id,
      description: 'You have to do ' + id
    });
  }
});

var NewTodoService = TodoService.extend({
  get: function(id, params, callback) {
    this._super(id, params, function(error, todo) {
      todo.user = params.user;
      callback(null, todo);
    });
  }
});

var app = feathers();

app.use('/v1/todos', TodoService.create())
  .use('/v2/todos', NewTodoService.create());

This makes version specific URIs very easy and I don't think it needs to be an explicit feature.
I am still inclined improving the REST-fulness by doing things like versioning through custom media types but I'll add a separate issue for that.

[norman784]

Well, its your project then I will redirect the suggestion to, the middlewares works the same as express? can I write a middleware that do the versioning url?

As I see you just use

var TodoService = Proto.extend({
  version: 1,
  get: function(id, params, callback) {
    callback(null, {
      id: id,
      description: 'You have to do ' + id
    });
  }
});

app.use(require('feather-version-middleware'));
app.use('/todos', TodoService.create());

// Then I get /v1/todos

Also talking about middleware It will be cool to have a router system

// controllers/v1/todo.js
module.exports = Proto.extend({
  version: 1,
  get: function(id, params, callback) {
    callback(null, {
      id: id,
      description: 'You have to do ' + id
    });
  }
});

app.use(require('feather-routes-middleware'));
app.use('/todos', 'v1/todos');

// Then I get /v1/todos

I know is possible, just want to know how middleware works on feather, because I have an app with this structure in express and will be cool to migrate to feather, that something like this.

var express = require('express')
    , app = express()
    , port = process.env.PORT || 5000
    , routes = require('express-path');

app.use(express.logger());
app.use(express.json());
app.use(express.urlencoded());

// Load routes
routes(app, [
  ['/status', 'api/status#index', 'all'],
  // email
  ['/v1/email/send', 'api/v1/email#send', 'post'],
  ['/v1/email/subscribe', 'api/v1/email#subscribe', 'post'],
  ['/v1/email/unsubscribe', 'api/v1/email#unsubscribe', 'delete'],
]);

app.listen(port, function(){
  console.log('Listening on port ' + port);
});

If says that I migrate to feather with the version middleware my routes will be just

routes(app, [
  ['/status', 'api/status'],
  ['/email', 'api/v1/email']
]);

This is the better way to don't mess with your goals and also have a very customisable module, so we don't need to hack the entire module to adapt to what we want.

Last question is, feather is just a CRUD or supports custom methods? just like my examples.

Regards

[daffl]

Technically what you want to do should work, you can definitely create your own middleware that does the version URIs for you. I haven't used express-routes but what basically happens when you do something like

app.use('/todos', {
  todos: [],

  // Return all todos from this service
  find: function(params, callback) {
    callback(null, this.todos);
  },

  // Create a new Todo with the given data
  create: function(data, params, callback) {
    data.id = this.todos.length;
    this.todos.push(data);

    callback(null, data);
  }
});

is for the REST services it registers something similar to app.get('/todos', someWrapperForServiceGet) and app.post('/todos', someWrapperForServiceCreate) and you can just add your own before and after that. http://feathersjs.com/#toc8 talks a little bit more of how services relate to your middleware.

Again, versioning is definitely a valid concern and we'll keep it in mind for the future.

[norman784]

Thanks, now I will do some homework and see whats happen.. Regards

[lock]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue with a link to this issue for related bugs.