Bluth API musings

api-ideas.js

/*** FUTURE API IDEAS ***/

// DYNAMIC URL (option 1)
cl.addPath('dynamic', '/items', 'post');
cl.dynamic.post();
cl.addPath('dynamic', '/items/:id', ['get', 'put', 'delete']);
cl.dynamic(3).get();

// DYNAMIC URL (option 2)
cl.addPath('dynamic', {
    '/items': 'post',
    '/items/:id': ['get', 'put', 'delete']
});
cl.dynamic.post();
cl.dynamic(3).del();

// DOES THIS WORK?
cl.addPath('dynamic', '/items/:id/:type');
cl.dynamic(5, 'code').get();
// OR
cl.dynamic({id: 5, type: 'code'}).get(); // GET http://example.com/dynamic/items/5/code

// MISSING STUFF
cl.addPath('dynamic', '/:id/items');
cl.dynamic.get(); // ERROR: id is not defined


// SUB-PATHS (same API)
cl.dynamic.addPath('comments', '/comments', ['get', 'post']);
cl.dynamic.comments.get(); // GET http://example.com/dynamic/comments

// SUB-PATHS (re-use existing path)
cl.addPath('points', '/points', 'get');
cl.dynamic.addPath(cl.points);
cl.points.get();         // GET http://example.com/points
cl.dynamic.points.get(); // GET http://example.com/dynamic/points


// HEADERS (per-client - applies to all calls for that client)
cl.setHeader('Content-Type', 'application/json');
cl.setHeader({Header1: 'something', 'X-Requested-With': 'PureAwesomeness'});

// HEADERS (per-path - applies to all calls for that path)
cl.path.setHeader('Content-Type', 'application/json');
cl.path.setHeader({Header1: 'something', 'X-Requested-With': 'PureAwesomeness'});

// HEADERS (per-call - applies to single call only)
// STILL NOT HAPPY WITH THIS ONE
cl.path.nextHeader('Content-Type', 'application/json').get();
cl.path.nextHeader({Header1: 'something', 'X-Requested-With': 'PureAwesomeness'}).get();


// ERROR HANDLERS - all error callback arguments depends on the transport used
// ERROR HANDLER (per-client)
cl.handleError(function () {});

// ERROR HANDLER (per-path)
cl.path.handleError(function () {});

// ERROR HANDLER (per-call)
// STILL NOT HAPPY WITH THIS ONE
cl.path.nextError(function () {}).get();
// ALTERNATIVE - JUST LEAVE IT TO THE TRANSPORT
cl.path.get().error(function () {});

// ERROR HANDLER (per-method, works with either per-client or per-path methods)
cl.handleError('post', function () {});
cl.path.handleError(['put', 'get'], function () {});


// RAILS-LIKE RESOURCES
cl.addResources('respath', '/photos');
// (Equivalent to:)
cl.addPath('respath', '/photos', ['get', 'post']);
cl.addPath('respath', '/photos/:id', ['get', 'put', 'delete']);
// (Allows:)
cl.respath.get();
cl.respath.post(data);
cl.respath(1).get();
cl.respath(1).put(data);
cl.respath(1).del();


// SWITCH SERVER - leaves all path definitions alone but changes base URL
cl.setServer(serverUrl);