Getting Started Using Cycle.io’s API With NodeJS

The recent public release of Cycle’s API has already seen all sorts of innovative uses, from automating the deployments of medical applications, to creating customized monitoring services to track specific performance metrics. Everything you can do in the portal can also be accomplished via the API — it’s actually the exact same API we used to build the portal!

In this article, we’re going to tackle setting up a NodeJS project that can query and display information about our servers running on Cycle.

Setting Up Our Project

First things first, we need to set up a new NodeJS project. Open your console and enter the following:

mkdir cycle-api-test
cd cycle-api-test
npm init

Follow the prompts to initialize your project. Once you’ve finished answering the questions, you should see a package.json in the folder.

Next, we need to install our dependencies. Our Node API library has some very powerful features when paired with Typescript, so I’m going to be using that. Feel free to use vanilla javascript, but keep in mind you will be missing some of the advantages of type completion.

npm install @cycleplatform/cycle-api

For Typescript, you’ll need to add a tsconfig.json file to the project root with the following contents:

{
  "include": ["src"],
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "lib": ["esnext", "dom"],
    "sourceMap": true,
    "strict": true,
    "noImplicitReturns": true,
    "moduleResolution": "node"
  }
}

This is a good quick setup for Typescript that will give you all the benefits of type checking and the ability to run the project quickly using ts-node.

Finally, we need to create our source directory and entry point.

mkdir src
touch src/index.ts

If you haven’t already, you’ll need to create an API key. Follow the instructions in the documentation here: https://docs.cycle.io/hubs/api-access/generating-api-keys. You’ll also need the ID of the hub you want to access, as all requests are scoped to the one you specify. To find this, use the portal and navigate to “Settings”. It will be listed on the right hand side of that page.

The hub ID, with a convenient copy button

If you’re a bit more adventurous, you may opt to use the API to list your hubs, iterate over them and select the appropriate one. I’ll leave this as an exercise for the reader :).

Okay, with all of that out of the way, it’s…

Time For Some Code

The first thing I want to do is get a list of my servers attached to Cycle.

Let’s break this down. First, we import the appropriate section from @cycleplatform/cycle-api . In this case, we’re dealing with our infrastructure. Next, we create an asynchronous function to make our request with. Inside this function, we call the getCollection function for servers, which will give us our list.

The API library is designed for functional programming, meaning instead of initiating an instance of it with your token, hub, etc., we opted to have these passed in when you call the function. The advantage is that you can import the exact functions you need, and easily switch between hubs / API keys. This also gives the user the ability to store their API key any way they choose.

The other thing you’ll notice is the await keyword. Every API call returns a Promise, and that promise contains an API result, which will either be a success or failure. By using the await keyword, we’re telling the function to pause execution until the promise has resolved, and then save the result to the resp constant.

This is where things start to get interesting. If you’re using Typescript, you’ll notice that when attempting to access the properties of resp , the only thing available is the ok property.

Only the ok property is accessible

Typescript is smart enough to figure out that the response can either be a success or a failure, and in order to ensure you check for an error code, will only make the value or error fields available after you determine if the request was successful. The advantage being, we don’t need to throw exceptions (which can lead to all sorts of fun, hard to discover bugs), and someone has to check for an error code before trying to access a property that might not exist. I think this is the best of both worlds when it comes to error checking in an API library.

Error is available if we know ok is false

The rest is pretty straightforward. We check if there is an error, and if so output it. If there isn’t an error, we log out the (nicely formatted) value instead.

Ok, let’s run this baby!

npx ts-node src/index.ts

If everything went well, you should see something like the following:

Congratulations! You’ve gotten your first response back from Cycle. As you can see, we’ve got an array of servers nested under the data field.

Let’s add some extra information by requesting the server stats along with our servers. We can achieve this through the meta portion of a query.

A query object can be passed in with nearly any request to modify or add extra information to a return. This is how you can manage pagination, include related resources, or add additional ‘meta’ information to the request.

According to the Cycle Docs we can see that the list server call accepts a stats meta field. Let’s add it in.

The result now contains much more detailed statistics information we can use to do anything from monitor our servers and send an alert when load gets too high, to designing our own personal monitoring dashboard!

That’s pretty much it! There are many, many things that can be achieved with the power of Cycle’s API. Keep a lookout for more articles highlighting different workflows and unique ways to utilize it. Next up, we’ll be featuring the notifications system and how you can get live updates directly from the platform itself.

Don’t forget to read through the docs!

Still Have Questions?

If you want to dive in and learn more, head over to our slack channel. Our community is growing, and our team hangs out there daily. Feel free to shoot us a message any time with your questions and we’ll be sure to respond!

Of course, for a more in-depth look at how to use Cycle, check out our documentation.

Learn More + Get Started Today

Thanks for checking out our blog! If you like what you read, please subscribe.

To learn more about Cycle, please visit https://cycle.io.

To create a free account, check out our portal!