Repository files navigation

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

Autocode is a fastest and easy way to build webservices and APIs that respond to external SaaS events. The Autocode ecosystemtreats external SaaS APIs as single-line function calls with the use of thelib package in NPM. The Autocode CLI allowsyou to interact seamlessly with the following components of Autocode:

1. Executing APIs on the Autocode standard library
2. 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 APIsfor yourself and other developers inminutes without having to manage servers,gateways, domains, write documentation, or build SDKs. Your development workflowhas never been easier - focus on writing code you love, let Autocode handleeverything else.

Autocode uses anopen specification calledFunctionScript for function definitions andexecution. If you run into concerns or questions as you're building from thisguide, please reference the FunctionScript repository. :)

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

1. Getting started
2. Creating your first service
3. Connecting service endpoints
4. Accessing your APIs from other applications
5. Accessing your APIs over HTTP
6. Version control and package management
7. Logging
8. Additional functionality
9. Acknowledgements
10. Contact

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

$ npm install lib.cli -g

And you're now ready to start building!

The first thing you'll want to do is create a workspace. Create a new directoryyou 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 tohttps://autocode.com/.Note that you can skip account creation withlib init --no-login.You'll be unable to use the registry, but it's useful for creating workspaceswhen 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 pointinto your service (useful if you only want a single entry point). This will automaticallygenerate a service project scaffold inautocode-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 automaticallycreated (__main__.js). Autocode comes paired with a simplelib command fortesting your functions locally and running them in the cloud.To test your function:

$ lib."hello world"

If we examine thefunctions/__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 thatcontext is a magic parameter (automatically populated withexecution details, when provided) as iscallback (terminates execution),so thesedon't need to be documented andcan not be specified asparameters when executing the function.

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 ourfunctions 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 overbuilding 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 withlib release will have adocumentation 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 thisdocs page.

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

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

$ npm install lib --save

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

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

constlib=require('lib');module.exports=async(a=0,b=0,context)=>{letresult=awaitlib[`${context.service.identifier}.add`]({a:a,b:b});returnresult*2;};

In this case, callinglib .add --a 1 --b 2 will return3 andlib .add_double --a 1 --b 2will return6. Thecontext magic parameter is used for itscontext.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 anenvironment or release (whereENV is your environment name or semver).

As mentioned in the previous section, you can use the NPMlib package that'savailable on GitHub and NPM to access yourAPIs from legacy Node.js applications and even the web browser. We'llhave more SDKs coming out in the following months.

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

constlib=require('lib');letresult;try{result=awaitlib.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';}elseif(name==='spock'){return'i think this feeling is called "pleased"';}else{thrownewError('Only kirk and spock supported.');}};

We definitely recommend using thelib library on NPMto make API calls as specified above, but you can also make HTTPSrequests directly to the Autocode gateway. HTTP query parameters are mappedautomatically 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 queryreturn`Hello${name}`;};

A quick note on version control - Autocode isnot a replacement for normalgit-based workflows, it is a supplement focused around service creation andexecution.

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

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

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

Logging for services is enabled by default. When running a service locally withlib . orlib .functionname, all logs will be output in your console. The verylast output (normally a JSON-compatible string) is the return value of the function.

To view remote logs (in dev or release environments), use the following syntax:

:: Lists all logsfor the service$ lib logs username.servicename:: Lists main service endpoint logsfor"dev" environment$ lib logs username.servicename[@dev]:: Lists service endpoint named"test" logsfor"dev" environment$ lib logs username.servicename[@dev].test:: Lists all logsfor"dev" environment$ lib logs username.servicename[@dev]*$ lib logs username.servicename[@dev].*

The default log type isstdout, though you can specifystderr withlib logs username.servicename -t stderr.

Limit the number of lines to show with the-l argument (or--lines).

Autocode comes packed with a bunch of other goodies - as we roll out updates tothe platform the serverless builds we're using may change. You can updateyour service to our latest build usinglib rebuild. If for any reason yourservice goes down and is unrecoverable, you can fix it with this command.

To see a full list of commands available for the CLI tools, type:

$ lib help

We've conveniently copy-and-pasted the output here for you to peruse;

*-b                   Execute as a Background Function-d                   Specify debug mode (prints Gateway logs locally, response logs remotely)-i                   Specify information mode (prints tar packing and execution request progress)-t                   Specify an Identity Token to use manually-x                   Unauthenticated - Execute without a token (overrides active token and -t flag)--*                  all verbose flags converted to named keyword parametersRuns an Autocode function, i.e. "lib user.service[@env]" (remote) or "lib ." (local)create [service]-n                   No login - don't require an internet connection-w                   Write over - overwrite the current directory contents--no-login           No login - don't require an internet connection--write-over         Write over - overwrite the current directory contentsCreates a new (local) servicedown [environment]-r                   Remove a release version (provide number)--release            Remove a release version (provide number)Removes Autocode package from registry and cloud environmentdownload [username/name OR username/name@env OR username/name@version]-w                   Write over - overwrite the target directory contents--write-over         Write over - overwrite the target directory contentsRetrieves and extracts Autocode packageendpoints:create [name] [description] [param_1] [param_2] [...] [param_n]-n                   New directory: Create as a __main__.js file, with the name representing the directory--new                New directory: Create as a __main__.js file, with the name representing the directoryCreates a new endpoint for a servicehostnames:add [source] [target]Adds a new hostname route from a source custom hostname to a target service you own.Accepts wildcards wrapped in curly braces ("{}") or "*" at the front of the hostname.hostnames:listDisplays created hostname routes from source custom hostnames to target services you ownhostnames:removeRemoves a hostname route from a source custom hostname to a target service you ownhttp-p                   Port (default 8170)--port               Port (default 8170)Creates HTTP Server for Current Serviceinit [environment]-f                   Force command to overwrite existing workspace-n                   No login - don't require an internet connection--force              Force command to overwrite existing workspace--no-login           No login - don't require an internet connectionInitializes Autocode workspacelogin--email              E-mail--password           PasswordLogs in to Autocodelogout-f                   Force - clears information even if current Access Token invalid--force              Force - clears information even if current Access Token invalidLogs out of Autocode in this workspacelogs [service]-l                   The number of log lines you want to retrieve-t                   The log type you want to retrieve. Allowed values are "stdout" and "stderr".--lines              The number of log lines you want to retrieve--type               The log type you want to retrieve. Allowed values are "stdout" and "stderr".Retrieves logs for a given servicerebuild [environment]-r                   Rebuild a release package--release            Rebuild a release packageRebuilds a service (useful for registry performance updates), alias of `lib restart -b`releasePushes release of Autocode package to registry and cloud (Alias of `lib up -r`)tokensSelects an active Identity Token for API Authenticationtokens:add-to-envSets STDLIB_SECRET_TOKEN in env.json "local" field to the value of an existing tokentokens:list-a                   All - show invalidated tokens as well-s                   Silent mode - do not display information--all                All - show invalidated tokens as well--silent             Silent mode - do not display informationLists your remotely generated Identity Tokens (Authentication)up [environment]-f                   Force deploy-r                   Upload a release package--force              Force deploy--release            Upload a release packagePushes Autocode package to registry and cloud environmentuser-s                   <key> <value> Sets a specified key-value pair--new-password       Sets a new password via a prompt--reset-password     <email> Sends a password reset request for the specified e-mail address--set                <key> <value> Sets a specified key-value pairRetrieves (and sets) current user informationversionReturns currently installed version of Autocode command line tools

If you're running a previous version and are having issues with the CLI,try cleaning up the old CLI binary links first;

$ rm /usr/local/bin/f$ rm /usr/local/bin/lib$ rm /usr/local/bin/stdlib

Yep, it's really that easy. To keep up-to-date on developments, pleasestar us here on GitHub, and sign up a user account for the registry. Youcan read more about service hosting and keep track of official updates onthe official Autocode website, autocode.com.

Autocode is a product of and © 2021 Polybit Inc.

We'd love for you to pay attention to@AutocodeHQ andwhat we're building next! If you'd consider joining the team,shoot us an e-mail.

You can also follow our team on Twitter:

• @keithwhor (Keith Horwood)
• @hacubu (Jacob Lee)
• @YusufMusleh (Yusuf Musleh)
• @threesided (Scott Gamble)

Issues encouraged, PRs welcome, and we're happy to have you on board!Enjoy and happy building :)

Special thanks to the people and companies that have believed in and supported ourvision and development over the years.

• Slack@SlackHQ
• Stripe@Stripe
• Romain Huet@romainhuet
• Chad Fowler@chadfowler
• Brian LeRoux@brianleroux
• Ahmad Nassri@AhmadNassri

... and many more!