README
Alchemy Resource
Alchemy Resource is an opinionated way to use the alchemy-ether implementation of the Alchemy Framework to create a RESTful, scalable and highly available API.
The opinions that Alchemy Resource has are:
- Resource APIs have only 4 actions that match directly to HTTP methods:
GET
isshow
,POST
iscreate
,PATCH
isupdate
andDELETE
isdelete
- The returned error message structure contains a
code
that is from a set of well defined error types (e.g.platform.not_found
), a human readablemessage
, and a UUIDreference
so API clients and providers have a shared key to discuss specific errors. - Service discovery is accomplished using RabbitMQ topic exchanges: A resource registers its path as a binding key on the topic exchange
resources.exchange
, e.g./v1/users
registers with the binding keyv1.users.#
, then all messages send to/v1/users
are sent with the routing keyv1.users
which routes messages to the resource. - Structured Logging is done via a RabbitMQ queue: Alchemy Resource asynchronously sends messages to a logging queue where a specialised service listens and writes to various outputs (database, console ...)
- Authentication is accomplished by a caller creating a session and sending the resulting session identifier in a header on each subsequent request: A
Caller
is resource that has a set ofpermissions
, e.g. a caller may be permitted to callshow
on theUsers
resource but notcreate
. ASession
andCaller
are both resources that are implemented using Alchemy Resource. Tocreate
a session a caller sends its id and secret to the Session resource, a session id and expiry is returned to be used for authentication. Currently sessions are stored in memcached, this will likely change in the future.
Other projects that are in different stages of development and open-sourcing that will enable a complete system are:
- Alchemy Auth implements the Session and Caller resources and handle the authentication tasks.
- Alchemy Router is a gateway and router that receives HTTP requests and sends them to the correct resource.
- Alchemy Logger receives structured logging messages and writes them to various outputs including Database, SQS and log entries.
Getting Started
To install Alchemy-Ether:
npm install alchemy-resource
This example creates a resource Hello
which is located at /hello
, then call its show
method:
AlchemyResource = require 'alchemy-resource'
hello_resource = new AlchemyResource.Resource("Hello", '/hello')
# The Hello resource implements `show` which takes a body and returns a string of the name
hello_resource.show = (context) ->
{body: "Hello #{context.body.name}"}
# Make show action public so no authentication is needed
hello_resource.show.public = true
# The resource service is created which contains the resource
service = new AlchemyResource.ResourceService('hello.service', [hello_resource])
# Start the Resource Service
service.start()
.then( ->
# Service sending message to the resource,
# it only knows the path and does not know where the service lives.
service.send_message_to_resource({
path: '/hello'
body: JSON.stringify({ name: "Alice" })
verb: "GET"
})
)
.then( (response) ->
console.log(response.body) # "Hello Alice"
)
.finally( ->
service.stop()
)
Examples
Documentation
This Alchemy Resource documentation is generated with docco from the annotated source code.
The Alchemy Resource package exports:
Resource the interface that is overridden to implement Resources.
ResourceService contains many resources and manages their discovery, authentication and logging.
Bam (a homage to Boom) contains the formatted errors to be returned.
MemcachedSessionClient the session client for memcached.
module.exports = { Resource: require('./resource') ResourceService: require('./resource_service') Bam: require('./bam') MemcachedSessionClient: require('./memcached_session_client') }
Contributors
- Graham Jenson
- David Mitchell
- Wayne Hoover
Changelog
2015-12-16 - Updating errors to Hoodoo Specification - Graham 2015-12-3 - Open Sourced - Graham & Wayne