Joule in 5 Minutes

You create a new Joule by forking an existing Joule or Joule template. The best way to start is to click 'Create a Joule` and select an existing template. One of our boilerplate templates is a great place to start if you don't have something specific in mind.

Creating a Joule

When you create a Joule you will be asked to give it a name. The name you specify will be used to create a fork in your GitHub account and as part of your Joule's API endpoint.

  • GitHub repo: {GitHub username}/{Joule name}
  • Joule endpoint: https://api.joule.run/{GitHub username}/{Joule name}

Test it out

Create a joule.

Deploying a Joule

Your Joule is already deployed! By forking a Joule you have created and deployed your Joule automatically without the need to manage any infrastructure.

You can find how to run your Joule yourself by going to the My Joules page and clicking on a Joule.

Redeploying a Joule

Joules are automatically deployed whenever there's a new commit that makes it into your master branch on GitHub. If your Joule contains any environment variables then it will be deployed whenever there's a change and you save the changes from your Joule's page.

What does a Joule look like?

Open up the GitHub repo for your Joule. You'll see the following structure:

/src
    index.js
    events.json-sample
    package.json
.gitignore
.joule.yml
README.md

Joule YAML

The .joule.yml file is your Joule's configuration file. It defines your Joule, methods, inputs, and responses. See the YAML documentation for more details.

index.js

This is the main entry point of your Joule. The exports.handler function is what kicks off your Joule. It receives event and context parameters.

The event object

The event object contains all of the input sent to your joule.

  • httpMethod - The HTTP method used to invoke your Joule (GET, POST, PUT, DELETE).
  • query - A key/value hash of the query string parameters.
  • post - A key/value hash of POST parameters including application/x-www-form-urlencoded and application/json.
  • headers - A key/value hash of incoming HTTP headers.

Here's an example of what event would contain for this API call to your Joule.

curl -X POST \
  -d '{"post_param":"param value"}' \
  -H 'Content-Type: application/json' \
  "https://api.joule.run/your_username/your_joule_name/path_param?param=value"

{
  httpMethod: "POST",
  headers: {
    'Content-Type': "application/json"
  },
  query: {
    param: "value"
  },
  post: {
    post_param: "param value"
  },
  path: [
    "path_param"
  ]
}

The context object

In order to send a response to the caller of your Joule you'll need to use the Response class.

var Response = require('joule-node-response');

exports.handler = function(event, context) {
  var response - new Response();
  response.setContext(context);
}

The Response class

To send back a response you will include the node-joule-response module and instantiate an instance of the returned Response class. In order to construct your response you'll call setContext() and optionally call setHttpStatusCode(), setHeader() and finally send().

The response module should already be in your Joule's package.json as joule-node-response. It's available via npm.

Here's an example of sending a response.

// require the response module
var Response = require('joule-node-response');

exports.handler = function(event, context) {
  var response = new Response();
  response.setContext(context);

  // At some point you will have result data you want to respond with
  var result = {
      user: {
          user_id: 12345,
          username: foo,
          email: bar@joule.run
      }
  };

  response.send(result);
};

The caller will get this response.

{
    user: {
        user_id: 12345,
        username: foo,
        email: bar@joule.run
    }
}

You can specify an error by calling setHttpStatusCode() with a non-200 status code.

// require the response module
var Response = require('joule-node-response');

exports.handler = function(event, context) {
  var response = new Response();
  response.setContext(context);
  response.setHttpStatusCode(400);

  // At some point you will have error data you want to respond with
  var result = {
      error: {
          message: "User not found"
      }
  };

  response.send(result);
};

The caller will receive a 400 Bad Request HTTP status code and this response:

{
    error: {
        message: "User not found"
    }
}

events.json

Also included in the package.json is joule-node-local and an events.json to use for testing your Joule in your development environment. events.json contains an array of key/value pairs that get sent to your handler as the event parameter, and running npm test will show a list of outputs for each set of inputs. This makes it easy to quickly test your Joule.

Test it out

Read our guide on locally running your Joule so you can test that it works correctly.