# user(s)112
# project(s)50
# build(s)305
Avg build time19.8s
Queue len0 (0.0)

The Public API

The API described below provides an access to the Ling Build Service (LBS), the service for packaging Erlang application code with the Ling virtual machine. The output image runs directly on top of the Xen hypervisor.


A user must register with the LBS before using the API. The credentials are passed along with requests using the basic HTTP authentication. Consequently, the LBS is accessed exclusively over HTTPS.

A user can add multiple projects to the LBS. The project is submitted to the build service as a single .zip archive. All project files are embedded into the output image and are accessible during runtime under the /project_name directory. For example, a user builds a project named ‘red’. The project has a file named ‘herring.png’ in its priv directory. The file will then be accessible during runtime as /red/priv/herring.png.

Typically, most of the project files are BEAM modules. The .beam modules are automatically recognized and converted to corresponding .ling modules.

The LBS maintains a queue of build requests. A single build can be active at any given time. After a successful build, the created image becomes ready for downloading. All images contain enough standard Erlang modules to bring up an Erlang shell. These include complete stdlib and kernel applications.

The API follows REST guidelines and prefers JSON as the data format. The format of the response depends on the Accept HTTP header of the request.

API Functions

GET /1/about

Returns a descriptive string about the service including its version. No authorization required.

GET /1/stats

Returns the current service statistics. For JSON requests, the service returns a JSON object with the following fields:

  • num_users – the total number of users registered;
  • num_projs – the total number of projectes created;
  • num_builds – the total number of successful builds;
  • cur_queue_len – the current length of the build queue;
  • avg_queue_len – the average length of the build queue;
  • avg_build_time – the average build time across projects in seconds;
The textual response is the concatenation of the field value using a pipe (|) character. The order of the fields is as follows: num_users, num_projs, num_builds, cur_queue_len, avg_queue_len, avg_build_time. The request does not require authorization.

GET /1/status

Returns the current status of the service. For JSON requests, a number is returned:

  • 0 – idle
  • 1 – building
  • 99 – down
For textual requests, the service returns a descriptive string. The request does not require authorization.

POST /1/users

Creates a new user. The body of the request is a JSON object describing the user. The following three fields must be present: user_name, email, password. The request does not require authorization.

GET /1/users/user_name

Retrieves information about the user. The only bit of information returned by the call is the user’s email.

PUT /1/users/user_name

Updates the user information. The body is a JSON object that may contain the following fields: email, password.

DELETE /1/users/user_name

Removes the user from the LBS. All project uploaded by the users are deleted along with the user information.

PUT /1/projects/proj_name

Creates a new project for the user or updates files of the existing project. The project name may not contain characters other than letters, digits, and underscores. The body of the request is the project archive. It must have a MIME type of ‘application/zip’.

GET /1/projects/proj_name

Retrieves the project archive.

DELETE /1/projects/proj_name

Removes the project including the cached images, if any.

GET /1/projects

Retrieves a list of projects created by the user. The list is a JSON list.

POST /1/build/proj_name

Request the image build for the project. The cached image is removed upon the request.

The body of the request may be empty or contain a JSON object with the following fields:

a list of standard libraries/applications to import. ‘kernel’ and ‘stdlib’ are auto-imported and must not be listed. Defaults to [].
a boolean flag that indicates that the project uses Elixir. Defaults to false.
a type of the output image. Set to ‘elf’ to generate a standard Xen-ELF image. Set to ‘ami’ to generate an Amazon Machine Image (AMI). BEWARE: AMI images are uploaded to Amazon S3 and are publicly accessible. Defaults to ‘elf’.

If the body of the request is empty, default values for build parameters are assumed.

GET /1/build/proj_name/image

Retrieve the newly built (or cached) image.

GET /1/build/proj_name/ami_id

Retrieve ID of the generated Amazon Machine Image (AMI).

GET /1/build/proj_name/status

Retrieve the status of the last build. The reply is a single integer value formatted as JSON:

  • 0 – build incomplete/not started
  • 1 – build ok
  • 99 – build failed

If the textual representation is requested a corresponding descriptive string is returned.

The service is free for any purpose, including commercial use. It is provided "as is", without any warranty.
More licensing options are available from
Cloudozer LLP.
E-mail: [email protected].