Permalink
bbca4f7 Jul 23, 2018
4 contributors

Users who have contributed to this file

@gojko @stojanovic @rezart @phips28
64 lines (43 sloc) 3.12 KB

API definition syntax

this is the API documentation for versions 2.x and later. If you are looking for older (1.x) versions, check out version 1.x API documentation

Claudia API builder makes it easy to configure and deploy API Gateway definitions together with a Lambda function, providing an abstraction that is similar to lightweight JavaScript web servers such as express.

var ApiBuilder = require('claudia-api-builder'),
	api = new ApiBuilder(),
	superb = require('superb');

module.exports = api;

api.get('/greet', function (request) {
	return request.queryString.name + ' is ' + superb.random();
});

For a more detailed example, see the Web API Example project.

Defining routes

An instance of the Claudia API Builder should be used as the module export from your API module. You can create a new API simply by instantiating a new ApiBuilder, then defining HTTP handlers for paths by calling .get, .put, and .post.

You can also create a generic handler for any method on a path, using .any. See the Web API Generic Handlers Project for an example.

Responding to requests

Claudia API builder will try to automatically format the result according to the content type. If you use the 'application/json' content type, you can respond with a String or an Object, the response will be correctly encoded or serialised into JSON.

You can either respond synchronously (just return a value), or respond with a Promise. In that case, the lambda function will wait until the Promise resolves or rejects before responding. API Builder just checks for the .then method, so it should work with any A+ Promise library.

api.get('/greet', function (request) {
	return request.queryString.name + ' is amazing';
});
api.post('/set-user', function (request) {
  return new Promise(function (resolve, reject) {
    // some asynchronous operation
  }).then(() => request.queryString.name + ' was saved');
});

To implement a custom termination workflow, use the request.lambdaContext object, and return a Promise that never gets resolved.

Detailed API documentation and examples