Basic Autocode API Plugin Example

API Plugins (also known as Connector APIs) are the building blocks of the Autocode Standard Library. They're a special kind of project that contain reusable logic intended to be called by Large Language Models (AI models like ChatGPT) or other Autocode projects. To that end, once deployed and shared, they appear in the Autocode editor's API autocomplete so that you or others you share with can easily discover them when creating other projects.

Creating API Plugins

To create a new API, head to your Autocode dashboard and press New API.

After selecting a name for your new API, open the functions/__main__.js project and you'll see an endpoint that looks like this:

/**
 * An example typed API that generates a hello world message
 *   Read more about typing at: https://github.com/acode/functionscript
 * @param {string} name The name to say hello to
 * @param {integer} count The number of times to say hello
 * @returns {object} body
 * @ {array} messages A list of messages
 */
module.exports = async (name = 'world', count = 10) => {
  count = Math.min(Math.max(1, count), 100);
  return {
    messages: Array(count).fill(`Hello ${name}, welcome to Autocode ${count} times!`)
  };
};

If you've worked on other Autocode projects, you might notice that this endpoint
looks a bit different from standard webhook endpoints. That's because this endpoint defines its parameters and return types using FunctionScript, Autocode's specification for turning functions into type-safe HTTP APIs. The comment block (lines between /** and */) is where everything happens. Here's more detail on what each line does:

The lines before the first @param describe what the API does.
@param {string} name The name to say hello to declares that the endpoint will take a string parameter called name.
@param {integer} count The number of times to say hello declares that the endpoint will take a integer parameter called count.
@returns {object} body declares that the API will return an object.
@ {array} messages A list of messages applies to the previous line, and declares that the object the endpoint returns will contain an array property called messages.
module.exports = async (name = 'world', count = 10) => { sets default values of 'world' and 10 for name and count. These will be used if the incoming request does not have values for those parameters.

Note: The comment block must go immediately above the line that exports the function (module.exports).

If a request comes in that doesn't match this typing (for example, a request that passes in a non-integer count parameter like 'hello'), Autocode will reject the request and your code will not run. Additionally, if your function returns a value that does not match the return type, your function will automatically return an error (though the code will still run).

You can designate parameters as optional by using null as a default value. For more on what you can do with FunctionScript, including a full list of types, check out the official docs.

Automatically Generated Docs

Your new Connector API also has automatically generated docs pages. Check yours out after saving your project by clicking the API link in the top left of your editor.

You'll see all the parameters, return values, and descriptions you documented in your the FunctionScript definition. This makes it easy to show others how to use your API!

Try updating a parameter name or type, saving, then refreshing your docs page to see how it updates.

Making Your Connector Public

By default, your Connector API's docs page is only visible to you. To make it appear in Autocode's Standard Library, open your project, in the editor, then press the Share button in the top right. You can share it publicly by changing Public Permissions, or you can share it individually by searching for a specific user.

Your API will also appear in your own API autocomplete as well as anyone that it's directly shared with. To see non-versioned releases (for example @dev) in the autocomplete, you will need to type @ before your API name like this:

await lib.username.@

Thank You!

We hope you found this guide useful. If you have questions or comments, feel free to let us know by joining our community Discord server.

Happy hacking!