Building an API in Airkit
REST APIs, at its core, are a means of communication. They allow for systems or applications to communicate and transfer data to one another. APIs are an integral part of the development of web services and make data digestible for a system, and allow you to write code to explicitly request data from a server.
For example, you can get the astronomy picture of the day by going to NASA’s website here, which is actually making an API request and displaying it on a page, or you can use their REST API to get the raw JSON data.
{
"date": "2022–03–24",
"explanation": "Peculiar spiral galaxy Arp 78 is found within the boundaries of the head strong constellation Aries. Some 100 million light-years beyond the stars and nebulae of our Milky Way galaxy, the island universe is over 100,000 light-years across….",
"hdurl": "https://apod.nasa.gov/apod/image/2203/noirlab2209a_ngc772.jpg",
"media_type": "image",
"service_version": "v1",
"title": "Arp 78: Peculiar Galaxy in Aries",
"url": "https://apod.nasa.gov/apod/image/2203/noirlab2209a_ngc772_1024.jpg"
}So, what’s the deal with APIs and Airkit?
REST APIs can be used to enable integrations with Airkit. One of the common use cases is triggering off an Airkit Journey using a REST API. For example, if you had a CRM, IVR, or custom application that you wanted to send data and trigger off an Airkit Journey, you would do that through an API.
You can have that API send data relevant to the user, trigger off an SMS notification that asks them to provide further information, and use the data to pre-fill the form for them as well, creating a seamless and frictionless experience.
That sounds super interesting, but I don’t know how to build an API
In traditional development, this requires setting up a development environment, writing your API methods using your programming language of choice, adding error handling to validate the requests, and a lot more depending on the scope of the API. And this is just to allow for testing your API locally. Deploying your API and providing a way to secure your api are also needed to build out your API.
What if you can do this all in the web browser without writing any code? Starting from creating your resources, building out the API methods, securing your APIs and deploying your API, Airkit’s Triggers Builder allows you to build out APIs all within the studio without having to write any code.
You only need to worry about understanding what API method to use, designing your API functionality using Airkit’s data operations, and structuring the response of the API.
What does this look like?
Triggers Builder is a builder in the Airkit Studio that allows you to define and manage how Journeys begin and also where you can create App APIs.
In the builder, you start by creating your URL Route. You can choose between an existing route or create a new one directly from the UI. You can also require an API key to be passed with the request to ensure that the request is secure.
And just by typing in what my URL route is to be named, and hitting create you have a URL Route and you can start designing my API.
Here, the new URL route will look like:
https://app.airkit.com/building-api-in-airkitDesigning the API
Here we’re going to build an API that when triggered, sends an SMS notification to a phone number– a simple Airkit experience.
Because you are creating a new resource and sending data (the phone number), you will need to make a POST request.
In Triggers Builder, you have the ability to create path parameters, query parameters and provide some sample data to test your API all within the studio. Create a path called send-sms and add a sample request body. This will allow you to test out how data flows throughout my API.
To design and build out what the API will do, you can add any combination of data operations to the flow. This can range from Creating Files, making HTTP requests, Filling PDFs, running Journey events, and much more!
The first data operation you will want to add is an Early Return data operation, which will allow you to use an Airscript expression and check to see if the request body is valid or not. If it isn’t valid, you can throw an error message for the user, else you can continue with the flow. Here you can write a conditional and check to see if there is a value for the phone number, and then if there is, check to see if it is a valid phone number.
If the request body does not meet either criteria, then throw an error message for the user and exit out of the flow and send back an error message as the response body (we’ll configure this towards the end).
Once you have the validation all set up, you can use the Start Journey data operation, which will allow you to trigger off an Airkit journey using a data operation. Here you can start a new session or lookup and existing session and pass the formatted phone number to the Airkit app to send a text message to the phone number in the request body.
Next, in order to send an SMS message, you can use the Run Event in Journey data operation, which will allow me to run a session event on a particular session. In order to designate what journey event to run, you need to create a Session event in Connections Builder. The session event that is run uses the send SMS notification action.
The last steps that you need to configure is your API Response, which includes your response headers, response status, and response body. For this API, you don’t need to pass any headers, but this can be used to give a more detailed context of the response.
For the response status, this is going to check to see if the request payload is valid. If it is valid, send back a 200 code or, if it isn’t valid, send back a 400 code.
Lastly, for the response body, we can send back metadata about the journey if the journey is kicked off properly, or send back the error message if it’s a bad payload.
Testing it out!
And just like that, you have created your URL route and designed your API. The only thing you have to do next is to publish your application! Publishing will make your API live and make it available to be used across other platforms.
Want to see how it works? Check it out below and send a POST request!
{
“phone”: ”insert your phone number here”
}Link to test out the API:
