Shortcuts With macOS Technical Note

Note: The specific features and functions of the Shortcuts application may vary depending on the macOS version you are using. For the most accurate and up-to-date information, we recommend visiting the official Apple website or checking the macOS user guide for the latest documentation.

Introduction

This technical note aims to guide you through the process of setting up a Shortcut to request the API version through the Cambrionix Hub API. The underlying logic here can be extended to automate various API calls using Shortcuts. Before attempting to automate more complex calls, we recommend familiarising yourself with Cambrionix Hub API user manual, as each API call may require different mandatory or optional parameters.

N.B. This will be easier to view in a pdf reader, so you are able to copy and paste sections of text. Browsers work too, but you just need to be mindful of your mouse-cursor placement or the browser will recognise the URL and attempt to take you there.

Jargon Buster

JSON

JSON stands for: JavaScript Object Notation. It is a lightweight language used to for storing and transporting data, in an easy-to-understand format.

It is not necessary to fully comprehend JSON in order to use the Shortcuts application but a basic understanding would be beneficial. You can read up more about JSON at w3schools.com.

API

API stands for: Application Programming Interface. They allow you to interface with an application. This document does not provide an in-depth explanation of the Cambrionix Hub API capabilities, you can find more detailed information in our user manual. For a broader understanding of APIs, the w3schools.com topic on this has some excellent resources.

Shortcuts

Shortcuts is an application developed by Apple. By using a series of 'actions', you can quickly get things done with your applications, with either a click or by asking Siri.

What is an action?

An 'action' is the building blocks of a shortcut. Using a series of actions, you can create complex workflows to run through with just a simple click or by asking Siri. Apple - Shortcuts User Guide for Mac is a great resource for further learning on the Shortcuts application.

Read on for how to use Shortcuts with the Cambrionix Hub API.

    URL Encoding

    A URL is made up of specific accepted characters, leaving a lot of characters that aren't allowed. Because of this, we need to encode the URL we're putting together in this document, so that those characters get parsed through correctly.

    Effectively, the first action we're going to be using in Shortcuts will 'encode' the URL from this:

    Copy 
    http://localhost:43424/?{"jsonrpc":"2.0","id":0,"method":"cbrx_apiversion"}

    To something like this:

    Copy 
    http://localhost:43424/%2F%3F%7B%22jsonrpc%22:%222.0%22,%22id%22:0,%22method%22:%22cbrx_apiversion%22%7D

    Albeit less readable to us humans, this is a genuine URL whereas the one above is not.

    e.g. This is what that looks like in Shortcuts

  1. 'URL Encode' action

    2. First, click on the '+' icon to get started. Then, in the search box, look for 'URL Encode' and double click/drag that over to the first step in the flow:

  2. Build the URL for the API call

    3. From here, we now need to tell this shortcut to communicate with the local API running on your machine. Once you've added the 'URL Encode' step, click into the 'Text' box of the 'URL Encode' action and add this:

    Copy 
    http://localhost:43424/?

    From here, we need to start inputting the JSON for the API call. This will need to be formatted in a single line.

    For requesting the API version, we can add this to the URL:

    Copy 
    {"jsonrpc":"2.0","id":0,"method":"cbrx_apiversion"}

    So, the full URL at this point should now look like this:

    Copy 
    http://localhost:43424/?{"jsonrpc":"2.0","id":0,"method":"cbrx_apiversion"}

  3. Make the API call

    4. 'Get contents of URL' is the action we need. This will allow us to make the API call - the 'URL Encode' action puts the URL together for us, the 'Get contents of URL' action will 'send' that URL to the Cambrionix API. Either double click or drag it over to below the first action.

    If you now send this call (with the Play Icon) and click on the quick-look button (image of the eye), you can drill into the response the API sends back. The response will be in JSON format.

  4. API Response in human-readable format

    5. The response from the API has all the information you've requested from it but it's wrapped in JSON. We can make use of another action here to format that more nicely for us. 'Get Dictionary Value' is the action we're looking for. Double-click or drag over to the workflow.

    When you drag this segment over to the workflow, you'll notice that it auto attaches itself and defines the 'Contents of URL' automatically. We then need to tell it what 'key' we are looking for in the response from the API. In this instance, we want the 'result' key, so we have this logic: 

    Copy 
    GET [Value] for [result] in [Contents of URL]

Conclusion

The aim of this document was to guide you through the process of setting up an automated API call to request the API version of the Cambrionix Hub API running locally on your machine. Utilising the resources linked in this document, and with a good understanding of APIs and JSON, you'll be able to evolve this into some complex workflows, executable with a click of the mouse. You'll vastly improve work efficiency and develop some 'cool' shortcuts to show off to colleagues.

Further Reading

Apple

Shortcuts User Guide - for Mac

Intro to Shortcuts on Mac

Navigate the action list in Shortcuts on Mac

Cambrionix

Cambrionix Hub API User Manual