There’s more talk out there about Apple Shortcuts these days, particularly since Apple’s announcements around iOS 18 and its upcoming improved support for Siri and Shortcuts, together and separately.
And thank god, because this app has been massively slept-on for far too long. It has so much functionality and extensibility, which makes it a veritable playground for the automation heads. Coming from a web development background really made Shortcuts appealing to me, because of things like API integration we’ll be talking about today.
If you haven’t taken the time to check out Shortcuts, there’s a good chance you may have already even uninstalled it, or stuffed it in a junk folder.
And I don’t blame you, because that’s what I did. It was literally called JUNKK with 2 Ks, and I am so sorry, Shortcuts. You deserved better. [conspiratorial side whisper] I think most of Apple’s other apps deserve that designation though, with the exception of Freeform.
If you have absolutely zero idea what Shortcuts actually is, go read my
But truly, Shortcuts is just plain chock-full of potential, and Apple keeps adding more—particularly with the introduction of artificial intelligence via OpenAI coming this fall to supported devices.
Here’s the thing: despite being incredibly powerful, like most consumer software companies—Apple didn’t immediately put their most powerful features front-and-center. And I get it… they’re not trying to overwhelm you, perhaps.
But these are some features you really need to know about—particularly if you have web development experience—because they unlock some super-powerful functionality in this app that takes it from useful to indispensable.
APIS: Beyond consumer-level novelty
After the initial novelty of Shortcuts ran out for me, I went in search of something to really knock my socks off.
Sign up for theCUT, the deBOTchery Apple Shortcuts newsletter!
- Shiny new tools to extend Shortcuts' capabilities, directly from the builders
- Super-useful new shortcuts released regularly
- Learn Apple Shortcuts with valuable vidseo tutorials
- Learn how to use AI chatbots like ChatGPT alongside Shortcuts, and connect your apps
(Why? I don’t know. I’m on the spectrum and I’m always pushing my limits because I guess I just want to see what’s out there. Plus, when you know what’s technically possible… a person like me really wants to find out how close we can get to it.)
And in my pursuit of something “deeper”—I discovered the Get Contents of URL action. We’ll discuss this later in greater depth, because it’s the center of this series.
But at this point, know this: being able to get data from a remote server through this Get Contents of URL action is basically the portal to Apple’s more advanced Shortcuts capabilities.
…and my journey into what I’ve started affectionately referring to as “The Fun Side of Shortcuts” began.
(Why? I don’t know. I’m on the spectrum and I’m always pushing my limits because I guess I just want to see what’s out there. Plus, when you know what’s technically possible… a person like me really wants to find out how close we can get to it.)
APIs are data docks
Before we break into the real good times, I want to give a quick 101-level overview of APIs. They’re really a very simple concept to understand once it clicks why we use them to begin with. All the questions of how to use them come after that.
APIs (Application Programming Interfaces) basically let your apps talk to one another.
Imagine an API like a shipping port. The port has different docks—or, endpoints. Each dock has been designed to transport different types of cargo—or in this case, data.
Interacting with an API involves determining which endpointAn endpoint in the context of APIs (Application Programming Interfaces) refers to a specific URL or URI (Uniform Resource Identifier) within an API that allows interaction with a particular resource or set of resources. you need to access, figuring out what information you need to provide it, making the request. But there’s one more part.
What can you do with APIs and Shortcuts?
In short: A LOT. As long as you can connect to another app, you have access to any data it gives you permission to access. And most apps have APIs available to at least their registered users, if not to the public without credentials.
But with Shortcuts, you get even more functionality, because you don’t need to be sitting in front of a computer to use your Shortcuts at all. Using APIs alongside Shortcuts, you can bring your data to you, or communicate with your data on its server—with the ability to render data as notifications and pop-ups.
- OpenWeatherMap: With a simple tap on your iPhone, you can pull the latest weather data and forecasts to plan your day, ensuring you know exactly what to expect without needing to open a dedicated weather app.
- Twitter: Automate your social media presence by scheduling tweets, pulling the latest blog headlines, and posting updates directly from your phone. (I’m a big fan of cross-posting Shortcuts, which let me simply copy the text I just posted on one platform, and instantly cross-post it to others without even having to open the app!)
- Fitbit: Track your daily fitness metrics, including steps, heart rate, and sleep data, all displayed directly on your phone to help you stay on top of your health goals.
- Google Drive: Manage your cloud files effortlessly by automating uploads, organizing documents, and even sharing files.
- Shopify: Monitor inventory levels, manage fulfillment, automate customer notifications, track sales, and manage your online store on the go.
- Stripe: Track payments, generate invoices, and manage your financial transactions directly from your iPhone.
- Trello: Automatically create or update tasks based on incoming emails or project milestones, keeping your projects organized and your team on track.
- Mailgun: Send personalized email campaigns, track engagement, and manage your mailing lists, ensuring your communication strategies are always active.
- Zoom: Schedule and manage meetings, send out invites, and even retrieve recordings, all from your iPhone, making it easy to stay connected with your team or clients,.
Communicating with REST APIs
Now, you can’t just roll up to the dock and start loading your ship. There’s a process, and that process involves HTTP methods. And HTTP methods are the core of REST.
REST stands for Representational State Transfer. It’s a fancy term, but at its core, REST is a set of rules and conventions for building and interacting with web services. It’s the architecture that most APIs today are built upon. When we describe an API that is built on this architecture, we call it “RESTful”.
In the world of APIs, the most common HTTP methods you’ll encounter are GET, POST, PUT, and DELETE.
HTTP Methods
These methods are how we interact with the endpoints. Depending on what you need to do—whether it’s retrieving data, submitting new information, updating existing records, or deleting something—you’ll use one of these methods.
Refining your request with parameters and queries
But how does the dock know exactly what you want? This is where parameters come in.
Parameters are the specifics you provide to ensure your request is accurate. Imagine you’re asking the dock workers to load your ship with electronics.
But what kind? Laptops? Smartphones? How many?
Parameters help you specify exactly what you’re after.
In an API request, parameters are usually added to the URL. For example, if you’re making a GET request to a weather API, your parameters might include the city name, the units for temperature (Celsius or Fahrenheit), and whether you want current data or a forecast.
A typical API request might look something like this:
https://api.weather.com/v3/wx/forecast/daily/5day?city=NewYork&units=metric
These parameters help the API know exactly what data to send you. In this example:
•city=NewYork is a parameter specifying the location.
•units=metric tells the API you want the temperature in Celsius.
Request/response
The important part to note about APIs is that they transport cargo (data) both ways: from your device to the app’s API with a request, and back with a response.
And it makes sense; you wouldn’t send back an empty ship, if you can help it. But also, in the case of APIs, the response holds great importance: it lets you know if the ship even made it there alright, and if it received the data we sent OK.
If it received the data, great! We get a ship full of data-cargo. But also, you get a receipt of sorts. In server-speak, we call this a 200 response—the server is saying “yep, we got it, here’s the data along with the receipt“.
If it didn’t receive the data, you’ll get some other kind of response. There are lots and lots of response options, and just as many reasons the error could happen.
Invalid credentials
Before the docks will take your request and give you the data, they require authentication—they need to know you’re who you say you are, and you need to have the appropriate permissions to be able to handle that data.
Like handing over your ID to the dockmaster to identify yourself, you’ll offer your credentials in API calls as well. This is usually in the form of an API keyAn 'API Key' is a unique identifier used to authenticate a user, developer, or calling program to an API (Application Programming Interface). It is a software intermediary that allows two applications to talk to each other.. And if that authentication process fails for whatever reason… well, no data for you.
These errors can have any type of error, and you’ll typically need to check the documentation to see what it means if it’s not particularly verbose.
Wrong dock
You may not even be in the right place. Depending on the endpoint you send your request to, you may be asking them for something they don’t have.
These typically result in 400 (or 40X) responses, such as the infamous 404: Not Found.
You asked the wrong way
Parameters required by that endpoint dictate the details you’re supposed to pass along to that dock with your request, and how they need to be submitted.
For example, you may need to tell a social media platform’s endpoint not just what content you want to post, but specifically what type it is, specifically from their selection of valid values.
Or, it may be expecting a boolean (true/false), and you provide it with a string of text that isn’t true or false. In any case, you’ll receive an error.
Understanding these common errors is crucial because it helps you troubleshoot issues when something goes wrong with your API call. You’ll need to refer to the developer documentation in that case—which I guarantee you’ll be doing a ton of anyway, especially if you’re just getting started with APIs.
Next up in the series: the REST API!
So, there you have it—a fairly solid foundation in APIs! BUT… I want you to have more. No: you need more. ????
Next up, we’ll discuss the REST API further, as well as what it looks like to make a HTTP request in Apple Shortcuts using the Get contents of URL action. followed by authenticating with them. I want you to first understand the process, then we’ll address how we pass our ID to the dockmaster and get our data.
See you there!
