How to use an API with Power Automate

Have you heard people around you using the word “API” and wondered what it is? Maybe you have a vague idea, but you still don’t know what to do with one? You have come to the right place, my fellow citizen developer!

“We need to pull information from this definitely-not-a-Microsoft-service, but don’t worry, there’s an API for that”.

In this blog post I’ll go through the basic terminology and give you a hands-on example of how to use an API with Power Automate.

To get started, there are some prerequisites:

  • You should know how to build simple flows in Power Automate (basically you should know how to add triggers and actions and how to use dynamic content). You should also know how to trigger a flow manually.
  • Using HTTP actions in Power Automate requires either a trial license or, for example, Power Automate per User plan.
  • You don’t need to know anything about APIs. Literally.

Why do we need APIs with Power Automate?

There are plenty of connectors available in Power Automate for different Microsoft and third-party services.

But sometimes the connector you need doesn’t exist or it doesn’t have the correct actions available. APIs expand the possibilities of Power Automate quite considerably, so knowing how to use one is a valuable skill for any citizen developer.

What is an API?

API stands for “Application Programming Interface”. But what is it?

One of the common ‘API for Dummies’ analogies is that it’s like a waiter in a restaurant; You tell the waiter what you want to order, the waiter delivers the order to the kitchen and then, hopefully soon, you get your food. API is like the waiter between the user and the system, sending information back and forth.

And here’s another analogy; There are many different types of cars, but they all have something in common. You drive all of them by using a steering wheel and pedals. Those are like the API of the car. You don’t have to know what is going under the hood, you just need to know how to drive one. Similarly, if you know how to work with one API, you can quite easily use any API.

And yes, these are awfully simplified explanations of an API, but it’s basically all you need to know for now. If you are interested to learn more, here is some further reading:

Does this thing have an API?

The API documentations are usually hidden away from regular users. You probably don’t need to know that Spotify has an API, or any other service you use daily. The easiest way to find an API documentation is to google with the name of the service and add API as a search word.

API terminology explained

Usually you can find documentation for an API you want to use. Some APIs have really nice, detailed documentations with good example requests and responses. Some APIs have poor documentation. But no matter what, knowing the basic API terminology helps you to navigate the documentations and find the things you need.

In this blog post I am roughly going through the following terms:

  • host, base URL and base path
  • endpoints
  • requests and responses
  • methods
  • JSON

And please don’t worry if some of this new stuff sounds confusing. It will make more sense later when we apply these to the sample flow.

Host, base URL and base path

REST APIs have a base URL to which the endpoint paths are appended. Base path is the URL prefix for the path.

The base URL usually contains the host and the base path, though the base path can vary. For example for Microsoft Graph API the base path can be either /v1.0/ or /beta/.

Endpoint

An endpoint is one end of a communication channel. Each endpoint is the location from which APIs can access the needed resources.

Here are some examples:

  • /me
  • /me/joinedTeams
  • /joinedTeams
  • /groups/teamID/members

Requests and responses

APIs work using requests and responses, for example you can use the API to request user details and get the user details as a response.

Method

Method is a way to interact with the resource. You can use the same endpoint with different methods, depending on whether you want to get information, change it or delete it. The API documentation tells you which method to use.

Here are two examples of methods:

GET: With GET you can usually retrieve resources, but not modify them in any way. For example you can make a GET request to get details of a specific user but you can’t change them.

POST: With POST you can usually create something new, for example add a new user.

JSON

JSON (JavaScript Object Notation) is a common format for sending and requesting data through a REST API. JSON is “self-describing” and usually very easy to understand.

Here is an example response with JSON:

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
    "businessPhones": [
        "+1 412 555 0109"
    ],
    "displayName": "Megan Bowen",
    "givenName": "Megan",
    "jobTitle": "Auditor",
    "mail": "MeganB@M365x214355.onmicrosoft.com",
    "mobilePhone": null,
    "officeLocation": "12/1110",
    "preferredLanguage": "en-US",
    "surname": "Bowen",
    "userPrincipalName": "MeganB@M365x214355.onmicrosoft.com",
    "id": "48d31887-5fad-4d73-a9f5-3c356e68a038"
}

In JSON there are name and value pairs. For example “displayName” is a name and “Megan Bowen” is a value. Basically JSON is like a list of data, just formatted in a special way.

Using API with Power Automate – Let’s build a sample flow

The Internet is full of public APIs to play with, and some of them don’t require any kind of authentication so they’re easy and quick to play with.

So let’s build a simple flow to get a hang of how to use an API in Power Automate.

Here’s what we want to do:

  1. Grab a random joke using a public API
  2. Send the joke to a user via Teams

I searched online for a suitable joke API and found this little gem: Official Joke API. Usually when I stumble upon a new API, I take a moment to browse through the documentation. But in this case, there is not much to read so we can go ahead and start building our flow.

Trigger

Every flow starts with a trigger. This time I’ll go with a manual trigger with an email input field (so I can also send bad jokes to my poor coworkers).

HTTP action

And now we need a joke. The action for this in Power Automate is HTTP. Official Joke API does not require authentication, so we can just set the method and URI.

The base URL for the Joke API is https://official-joke-api.appspot.com/. There is no base path in this particular case.

There are several endpoints available for the Joke API, but in this exercise I’ve decided to use /random_joke.

The API documentation doesn’t say which method to use, but in this case we can safely assume that the method is GET since we only want to grab a new joke.

Method: GET
URI: https://official-joke-api.appspot.com/random_joke

Now save the flow and make a test run. If everything works, you should have a little joke in the body of your HTTP action in JSON format. Here’s an example:

{
  "id": 162,
  "type": "general",
  "setup": "What did Michael Jackson name his denim store?",
  "punchline": "Billy Jeans!"
}

Make sure to copy the text content from the body field. We need it in the next step!

Parse JSON

We get the joke in neat JSON format, but to separate the setup from the punchline, we need the Parse JSON action. Parse JSON… parses the JSON so we can use the values later as dynamic content.

So, as the content we set the body from the previous HTTP action. And then we need a schema to define the structure and the content of a JSON object.

But from where is this schema coming?

If you have followed my instructions carefully, you should have the JSON content copied. If not, go ahead and do it now. (Or be lazy and copy the JSON example above.)

Choose the generate the schema from a sample (because we have a sample; the JSON we copied from the HTTP request body field).

Paste the JSON from the HTTP request body to the sample editor and click “Done”. It will generate the schema for you automatically.

JSON Schema is a grammar language for defining the structure, content etc.

For example here we can see that ID is a whole number (integer) and the joke is text (string).

{
     "type": "array",
     "items": {
         "type": "object",
         "properties": {
             "id": {
                 "type": "integer"
             },
             "type": {
                 "type": "string"
             },
             "setup": {
                 "type": "string"
             },
             "punchline": {
                 "type": "string"
             }
         },
         "required": [
             "id",
             "type",
             "setup",
             "punchline"
         ]
     }
 }

Now we have the joke, and we have parsed it with Parse JSON action. We can now use the setup and the punchline as separate dynamic values.

Post message

I want to use the Flow bot to post the messages so I choose the action “Post a message as the Flow bot to a user”.

I add the email from the trigger to the recipient field. But to the message I can choose values from the Parse JSON action. Pretty cool.

For the first message I want the setup value and for the second I want the punchline value. And a little 10 second delay between since isn’t that how you tell these jokes in real life? 😎

Now we have all the blocks ready in our flow and we can go ahead and test it. I hope you get a better joke than me though.

Congratulations, you have now successfully built a cloud flow using an API. And this is almost all there is to it. Well, not really. But understanding the basic terminology and how to implement things with Power Automate certainly helps you to get started, and experimenting does the rest.

And remember, if you need help, we’re here too.

Leave a Comment