- By Gojko Adzic
Claudia 2.0 is now available on NPM, along with Claudia API Builder and Claudia Bot Builder 2.0 versions, bringing support for dynamic response codes, easier custom header control, lambda proxy APIs, generic method handlers and wildcard path parameters, and integrating with the latest AWS API Gateway release.
- Easier dynamic request processing
- Using the API Gateway Proxy Request object
- Deploying proxy APIs
- Why the major version change?
Easier dynamic request processing
The most important new benefit for developers is probably being able to specify a response status code dynamically. Use the optional third argument to the ApiResponse
constructor:
The new API Gateway integration also makes it easier to support dynamic response headers, so you no longer need to enumerate all the headers upfront.
You can also use the new ANY
mapping type to wire up a handler for all supported HTTP methods:
Check out these example projects demonstrating the new features:
- Generic Handlers – hooking up to
ANY
method and using{proxy+}
wildcard paths. - Using dynamic HTTP status codes in responses
Using the API Gateway Proxy Request object
When we released the first version of Claudia, there was no quick and easy way to build web APIs on Lambda with API Gateway. Claudia API Builder allowed developers to use simple request handlers, as expected from a modern light-weight web server. A big part of that was creating a generic request object interface, that packaged all the request parameters, headers and authentication info. With the September 2016 update, API Gateway caught on significantly, offering their own version of the generic request object, containing mostly the same information, but with slightly different key names and structure.
With version 2.x, Claudia API Builder allows you to choose the format of the request object for your handlers. By default, it will wrap the API Gateway Proxy object and convert it internally into the current interface, to keep backwards compatibility. Pass AWS_PROXY
to the ApiBuilder
constructor to turn off the conversion, and receive the API Gateway Proxy Request object directly:
Going forward, it probably makes more sense to just adopt the API Gateway Proxy object and use it directly, as that would allow you to benefit from the new features of API Gateway as soon as they are released.
- With 2.x, the default format will be Claudia API Request, and you can choose to use API Gateway Proxy objects
- With 3.0 (in roughly six months), we’ll switch the default to be API Gateway Proxy, and you’ll be able to use old request formats
- With 4.0 (in roughly one year), we’ll remove support for the Claudia API Request object
Deploying proxy APIs
As an alternative to using claudia-api-builder
, you can now also deploy API Gateway integrations that just proxy all request information to your Lambda function. Claudia 2.0 supports that with the additional --deploy-proxy-api
argument. This is a good option for integrating existing web frameworks and doing more complex integrations, instead of just managing a simple Web API.
- Read more about this in the Deploying a Proxy API Tutorial
- Check out the Proxy API Example Project to see this in action
- Read more about proxy integrations at the API Gateway Developer Guide
Why the major version change?
The September 2016 API Gateway update last week introduced several major changes that make it easier to link Lambda and API Gateway, replacing a lot of the functionality that Claudia did separately in version 1.x. There were several major underlying changes that require updating both the deployment tool and API builders at the same time, hence the bump to a major version. That will ensure that people don’t update only one component by mistake.
We’re also using this opportunity to do some house-keeping and drop support for Node 0.10 which is not going to be supported in Lambda any more soon. We’ll no longer test Claudia modules with 0.10, so if you still need to use 0.10 APIs, then use 1.x version of Claudia. Going forward, we’ll also use this opportunity to start switching the source code to ES6, and update the development toolkit a bit, moving away from jshint/jscs to eslint.
The new version is completely backwards compatible with client code for 1.x, but several features that are no longer necessary are deprecated. Check out Migrating to 2.0 tutorial for more information.
Interested in Claudia.js? Get notified when we release a new version.
Low-volume, high value mailing list, no ads or spam.