<img src="https://content.public.files.stdlib.com/shared/static/branding/autocode-logo-wordmark.svg" width="300">

Autocode Setup | Node | Web | Python (alpha) | Ruby (alpha)

Introduction

Autocode is a fastest and easy way to build web services and APIs that respond to external SaaS events. The Autocode ecosystem treats external SaaS APIs as single-line function calls with the use of the lib package in NPM. The Autocode CLI allows you to interact seamlessly with the following components of Autocode:

Executing APIs on the Autocode standard library
Uploading new APIs / web services to Autocode's hosting platform

Autocode is based on Function as a Service ("serverless") architecture, initially popularized by AWS Lambda. You can use Autocode to build modular, scalable APIs for yourself and other developers in minutes without having to manage servers, gateways, domains, write documentation, or build SDKs. Your development workflow has never been easier - focus on writing code you love, let Autocode handle everything else.

Autocode uses an open specification called FunctionScript for function definitions and execution. If you run into concerns or questions as you're building from this guide, please reference the FunctionScript repository. :)

You can view services published by our large and growing developer community on the Autocode standard library page.

lib-process

Getting started
Creating your first service
Connecting service endpoints
Accessing your APIs from other applications
Accessing your APIs over HTTP
Version control and package management
Logging
Additional functionality
Acknowledgements
Contact

Getting started

To get started with Autocode, first make sure you have Node 8.x or later installed, available from the official Node.js website. Next install the Autocode CLI tools with:

$ npm install lib.cli -g

And you're now ready to start building!

Creating your first service

The first thing you'll want to do is create a workspace. Create a new directory you intend to build your services in and initialize the workspace.

$ mkdir autocode-workspace
$ cd autocode-workspace
$ lib init

You'll be asked for an e-mail address to log in to the Autocode registry. If you don't yet have an account, you can create one by going to https://autocode.com/. Note that you can skip account creation with lib init --no-login. You'll be unable to use the registry, but it's useful for creating workspaces when you don't have internet access.

Next, create your service:

$ lib create <service>

You'll be asked for a default function name, which is the entry point into your service (useful if you only want a single entry point). This will automatically generate a service project scaffold in autocode-workspace/<username>/<service>.

Once created, enter the service directory:

$ cd your_username/your_service

In this directory, you'll see something like:

- functions/
  - __main__.js
- package.json
- env.json
- WELCOME.md
- README.md

At this point, there's a "hello world" function that's been automatically created (__main__.js). Autocode comes paired with a simple lib command for testing your functions locally and running them in the cloud. To test your function:

$ lib .
"hello world"

If we examine the functions/__main__.js file, we see the following:

/**
* A basic Hello World function
* @param {string} name Who you're saying hello to
* @returns {string}
*/
module.exports = async (name = 'world', context) => {
  return `hello ${name}`;
};

We can pass parameters to it using the CLI by specifying named parameters:

$ lib . --name "dolores abernathy"
"hello dolores abernathy"

Note that context is a magic parameter (automatically populated with execution details, when provided) as is callback (terminates execution), so these don't need to be documented and can not be specified as parameters when executing the function.

Pushing to the cloud

To push your function to a development environment in the cloud...

$ lib up dev
$ lib your_username.your_service[@dev]
"hello world"

And to release it (when you're ready!)

$ lib release
$ lib your_username.your_service
"hello world"

You can check out your service on the web, and use it in applications using our functions gateway, api.stdlib.com.

https://your_username.api.stdlib.com/your_service/

That's it! You haven't written a line of code yet, and you have mastery over building a service, testing it in a development (staging) environment online, and releasing it for private (or public) consumption.

Note: By default, APIs that you publish with lib release will have a documentation page in the Autocode public registry. You can keep your page private, as well as restrict execution access or add collaborators to your API, by modifying your API's permissions. For more information, see this docs page.

Another Note: Staging environments (like the one created with lib up dev) are mutable and can be replaced indefinitely. Releases (lib release) are immutable and can never be overwritten. However, any service can be torn down with lib down <environment> or lib down -r <version> (but releases can't be replaced once removed, to prevent mistakes and / or bad actors).

Connecting service endpoints

You'll notice that you can create more than one function per service. While you can structure your project however you'd like internally, it should also be noted that these functions have zero-latency access to each other. You can access them internally with the lib package on NPM, which behaves similarly to the lib command for testing. Use:

$ npm install lib --save

In your main service directory to add it, and use it like so:

functions/add.js

module.exports = async (a = 0, b = 0) => {
  return a + b;
};

functions/add_double.js

const lib = require('lib');

module.exports = async (a = 0, b = 0, context) => {
  let result = await lib[`${context.service.identifier}.add`]({a: a, b: b});
  return result * 2;
};

In this case, calling lib .add --a 1 --b 2 will return 3 and lib .add_double --a 1 --b 2 will return 6. The context magic parameter is used for its context.service.identifier property, which will return the string "your_username.your_service[@local]" in the case of local execution, "your_username.your_service[@ENV]" when deployed to an environment or release (where ENV is your environment name or semver).

Accessing your APIs from other applications

As mentioned in the previous section, you can use the NPM lib package that's available on GitHub and NPM to access your APIs from legacy Node.js applications and even the web browser. We'll have more SDKs coming out in the following months.

An existing app would call a function (username.bestTrekChar with version 0.2.1):

const lib = require('lib');

let result;

try {
  result = await lib.username.bestTrekChar['@0.2.1']({name: 'spock'});
} catch (err) {
  // handle error
}

// do something with result

Which would speak to your API...

module.exports = async (name = 'kirk') => {

  if (name === 'kirk') {
    return 'why, thank, you, too, kind';
  } else if (name === 'spock') {
    return 'i think this feeling is called "pleased"';
  } else {
    throw new Error('Only kirk and spock supported.');
  }

};

Accessing your APIs over HTTP

We definitely recommend using the lib library on NPM to make API calls as specified above, but you can also make HTTPS requests directly to the Autocode gateway. HTTP query parameters are mapped automatically to parameters by name.

https://username.api.stdlib.com/liveService@1.12.2/?name=BATMAN

Maps directly to:

/**
* Hello World
* @param {string} name
* @returns {string}
*/
module.exports = async (name = 'world') => {
  // returns "HELLO BATMAN" from above HTTP query
  return `Hello ${name}`;
};

Version control and package management

A quick note on version control - Autocode is not a replacement for normal git-based workflows, it is a supplement focused around service creation and execution.

You have unlimited access to any release (that hasn't been torn down) with lib download <serviceIdentifier> to download and unpack the tarball to a working directory.

Tarballs (and package contents) are closed-source. Nobody but you (and potentially your teammates) has access to these. It's up to you whether or not you share the guts of your service with others on GitHub or NPM.

As mentioned above: releases are immutable and can not be overwritten (but can be removed, just not replaced afterwards) and development / staging environments are mutable, you can overwrite them as much as you'd like.

Logging

Logging for services is enabled by default. When running a service locally with lib . or lib .functionname, all logs will be output in your console. The very last output (norma

Cli

Install / Use

README