One of the primary ways to use Airkit Studio is to create an application that takes information from a user or external system, asks the user to manipulate the data and then send the output to a system of a record.
One way your app can communicate with external apps is through their API. In this example we will walk through setting up a simple connection that does an HTTP Request. We are going to build out a simple application that POSTs some user input to a service and displays the response.
Basic Card With Input and Button
Create a new App. Rename My First Card View to Send Data View. Remove the My First Label by clicking on the trash can next to it. Let's add a String Input to the view.
Next add a button. Set the button text to "Post Input". Lastly, add a label to the view. Your View should now look like this:
In order to make this work, we will need a couple of variables on this Card View. With Send Data selected, add two text variables. One called input and the second called output.
Set the value of the string input to "input" and the value of the label to "output".
We will come back to this view and hook the rest of it up once we have created connection.
Creating a New Data Operation
Click on Connection Builder on the left and add a new Data Operation. Set the title of the data operation by double clicking on it in the inspector. Change the name to "HTTP - Post Data". It is not a requirement, but it is a good convention to name your Data Operations in a way that indicates their primary operation.
Under Inputs in the inspector, add a Text Input and name it dataString. You will now have an input to fill out in the start frame on the stage. Change the value of the dataString to something like "some test input." Because this is the start frame, this data will be passed directly to the first connection frame. All connections start with one frame. Select the gear next to the header of the frame and select HTTP Request as the frame type.
Notice how the frame changes to provide you with the options you need to complete your HTTP Request. In this example we will create a simple HTTP Post request. Let's start by setting up a listener at Request Catcher. Enter a name for catcher and click Get Started. Keep this window open for the rest of the demo. Copy the URL part of the curl request on the Request Catcher page.
Back in Connection Builder, change the Method of your HTTP Request to POST and paste in the url. Notice, because the URL Box is an expression, you will need to wrap the URL in quotes to have it treated like a string.
In the Body expression editor type in the name of the input we created, dataString. Note, this is a variable so we do not need to wrap it in a string. At the top of our Connection Frame, on the right hand side of the stage there is a Play Button. Clicking this button will run this particular frame.
Scrolling down to the bottom of the frame you will notice a section in the Connection Frame called Run Results. Clicking on rawResult should show the response of the request. In this case we can see that our request was successful because we have a response of 200 from the server. We can also go over to our request catcher page and see that he response came in.
We have one last step in Connection Builder before we hook this up to the app. We need to pass something back to the app after the Connection is run to let the user know it was successful. The raw result is too much information. Clicking on the plus button under the frame inserts a new frame after the HTTP request before the end. Change the frame type of this frame to Transform. This frame type simply takes input, allows you to preform some Airscript on the input and format some out.
We are doing something super simple here. The body of the rawResult is a simple text string that would make sense to our user, "request caught". Let's also fix the capitalization. In the Transform's expression editor type the following:
TITLECASE( rawResult.body )
Hit the play button on this connection frame and notice the output.
Great. Now that is something that the user can read. The last step in the connection is setting the return value in the end state. Go to the bottom of the stage and select "transform" as the return value of the connection.
Putting it all together
The last step in the process is hooking up our connection to the Card View. Go back to App Builder and select the Post Input Button in the Send Data View. In the inspector on the right switch to the actions tab. Click the plus button next to the Clicked Event and select Run Data Operation from the App Section.
The Action Editor will pop up. Select the HTTP - Post Data operation. Set the dataString input to be "input" and set the output to "output."
Click save. Click the debugger play in the upper right hand corner of the window. Launch the App from the web channel. Enter some input into the text box and click the Post Input Button. You should see Request Caught displayed.
In this example you learned:
- How to create a simple HTTP data operation
- How to transform the output of a data operation to be human readable with Airscript
- How to connect a data operation to a Card View Event.
This is a very simple example of an HTTP request, but it sets the building blocks for interacting with any accessible API.