Introduction

This quickstart tutorial shows how to connect to a 3rd party REST API using API Express. In this tutorial you will learn:

• Connecting to a 3rd party REST API.
• Our recommended approach to using 3rd party REST APIs in your app.

OpenWeather API

This tutorial uses the OpenWeatherMap API. Please sign up for a free account to get an API key to use the service.

Creating an API Express Project

To start you are going to create an API Express project.

1. Go to the API Express tab.
2. Click the Create new project button.
3. For the name, enter weatherAPI. Optionally enter the API description.

The visual service editor will load where you will use the REST component. But first, you need a place to store the API key for the service.

Storing the API Key

The API key (called appid in OpenWeatherMap) rarely changes so we want to store it in one place so we can easily reference it in the API. For this, you are going to use the Service keys functionality.

1. From the newly created API Express project click on Service keys page.
2. For key name enter: appid.
3. For the key value, paste the appid from the OpenWeatherMap site. You can find the appid on this page.
4. For description enter: Weather API key.
5. Click Add key to save this key.

Now the API key is safely and securely saved on the server. Next, let's work on setting up the REST component.

Using the REST component

In this step, you will add and configure the REST component.

1. From the main API page click new service link.
2. For Service group name enter: conditions.
3. Select the Custom REST API option and click the Create button. The visual service editor will load.
4. Select the Start component (first) and under Service section set its URI template to: weather. This is the name of the service.
5. The OpenWeatherMap service requires two parameters to work: appid and a location. We already took care of the appid. In this step, we need to create the location parameter which will be passed to the weather API. Under Request Query Parameter enter: location (String type).
6. Next drag and drop the REST component into the square between the Start and End components.
7. In the REST Service section, for the URL, enter http://api.openweathermap.org/data/2.5/forecast.
8. In Request Query Parameters create a parameter called: q and map it to the PARAMS.QUERY.location value. In this example, q is the parameter used by the OpenWeatherMap API and it is mapped to a location parameter in the API Express service you are creating.
9. In the same section, paste the appid* parameter and map it to PARAMS.KEYS.appid. Any keys you create can now be accessed in the service editor.

Next, you will need to generate the API Express service response by testing the service.

Setting REST Component Response

To set the REST component you will need to test the service.

1. Select the REST component and click the Generate button.
2. On this page, you can test the 3rd party REST API. You will need to enter a location. The appid is already pre-filled.
3. Click Run REST API to test the API. The service response will be displayed below.
4. Next click the Import response button. This will use the response from the weather API as the response of the REST component.

Setting Service Response

The last step is to set the API Express service response. That's the weatherAPI service.

1. Select the End component.
2. Under Response Body you will see that Use as response is set to BODY. BODY means using the response from the previous component which the REST component. That's what you need in this example. To learn more about the BODY object, go to the Components Data page.
3. Click the Save button and you are ready to test the service.

Testing the service

To test the service click the Test button. A new browser tab will open where you can test the service you just created. You only need to enter a location.

Creating App to Use the API

Now that now, when you have created a backend for an app, the next step is to build the app UI.

🚧

Important Note!

Note that the option of creating new apps with the Ionic framework was removed but we still support the projects that were created with it earlier.

To create a new app:

1. Go to the Apps page.
2. Click the Create new app button.
3. For the app name, enter: WeatherApp.
4. Select the Ionic Blank template (should be automatically selected) and click Create. The App Builder visual editor will load the app.

Next, you are going to import the REST API service you just created.

Importing API Express Service

API Express services can be quickly imported into the app.

1. Click Create new > API Express service.
2. Select the API Express project you just created.
3. You will see the conditions/weather endpoint REST API. Check the weather checkbox and click the Import selected services button.
4. The API Express service is now imported under the Services folder.

Open the service to see that everything is preconfigured.

It's a good idea to test the service inside the App Builder. To do that:

1. Open the service, then go to the Test tab.
2. Open the Query String tab and enter a test value for location.
3. Click Test to test the service. You should see the response in the Response section.

📘

Editing Services

If you need to make changes to the services it is recommended to make any changes to the service in API Express, test the service there again and re-import it. If you re-import the service, any mappings you have set for the service will be removed.

Another option (more advanced) is to edit the service in API Express and then edit the service in the App Builder. This way you don't need to re-import it.

❗️

Re-import the service

If you re-import a service that has been used on a page, all mappings and callbacks will be removed.

Now that you have imported the service, it's time to build the app UI.

Designing Pages

The app UI will consist of one page. You will be able to enter a location and display conditions for that location.

1. Open the Pages > index page.
2. Click on the Header and in Properties change the Text property to Weather App.
3. Open the Pages > Screen1 page.
4. From PALETTE, drag & drop the Input component. In Properties, set the Placeholder to: Enter location.
5. Below the Input component, drag & drop the Button component. In PROPERTIES, change the Text property to: Show Weather.
6. Next, add the List component below the button. The List component has three default items.

Now let's work on using the service you imported on this page.

Creating App Model

The app needs a model to represent the data on the client.

1. Go to Project > Model.
2. For the model name, enter Weather and click the Add button.
3. Create four properties in the Weather object:
   • location (String)
   • city (String)
   • description (String)
   • temperature (String)

That's it for the UI model. Next, you are going to add and map the service.

Using the Service on a Page

Let's complete the steps so we can invoke the service and display the result on a page.

1. Open the SCOPE tab.
2. At the top add a variable called weather, set its type to Weather, and click Add.
3. Next, you need to create a function that will call the REST API. For function name enter: getWeather (Scope function) and click Add.
4. The function code editor will open. Select the TemperatureAPI_conditions_weather_get service and drag and drop it inside the editor. The code to invoke the service is automatically inserted.
5. Click on the first CLICK TO EDIT MAPPING label to do the input mapping (from scope to service).
6. Click Expand all on both sides of the mapping editor.
7. By using drag and drop create the following mapping:
   • weather/location to query/location
8. Click the Save & Replace button. You will be back in the code editor and the mapping code will be automatically generated.
9. Click on the CLICK TO EDIT MAPPING label to open the visual mapping editor. This will allow you to map the data from the service into the scope.
10. Click Expand all on both sides of the mapping editor.
11. By using drag and drop, create the following mappings:

• weather/weather[i]/description to weather/description
• main/temperature to weather/temperature
• name to weather/city

12. Click Save & Replace to save the mappings. You will be back in the scope editor and the mapping code will be automatically inserted.

The next and the last step before testing is binding the scope data to the page to display the weather information.

Displaying Weather Information on Page

In this step, you are going to bind the scope to the page to display weather information on the page.

📘

Code assist

As you are binding a scope to the page, you can use code assist to help you enter variables. To invoke code assist, click ctrl+spacebar.

1. Switch back to the DESIGN tab.
2. Select the Input component and under PROPERTIES, add a new property called ng-model. Set its value to: weather.location. You are binding the input field to a variable in AngularJS scope.
3. Select the button and for its ng-click property set it to: getWeather() function.
4. Next, select the first list item and set its Text property to {{weather.description}}.
5. Set the second list item to {{weather.city}} and the third list item to {{weather.temperature}}

Save all the changes and you are ready to test the app.

Testing App

To test the app in the browser simply click the TEST button. The app will launch in the browser inside a frame that looks like a phone.