Exploring and Integrating Web Services in the Intel XDK

The Develop tab of the Intel® XDK development environment lets you explore a collection of third-party web service APIs (cloud services). In addition to the built-in third-party web services, the Develop tab helps you integrate other existing web services for use within the Intel XDK, such as those developed specifically for your app. Use these platform-independent web services to create apps that:

• Present content, such as timely news, weather, and business information.
• Present location information visually on a map.
• Share information between specific devices or users.

The collection of services provided by the Intel XDK does not constitute an endorsement of these services by Intel, they are simply being provided as a convenience to you, the developer. You are under no obligation to use the services provided by this feature; you may use any cloud services that are appropriate for your app. Please contact your third-party cloud services provider(s) for information regarding service costs and licensing and for technical and programming help.

With most web services you need to access the service provider's web site, create an account, read the terms and conditions and manage your account. Then you use your account to obtain any API key(s) needed for selected services from each service provider.

When to Use the Develop Tab to Integrate a Service

The bottom-left part of the Develop tab lets you:

• Integrate the data feed and other capabilities of web services into graphical parts of the Intel XDK, such as the App Designer and App Starter.
• Explore the APIs for a chosen service.
• Share the integrated services with others.

If the above reasons are not important, and you already know the chosen web service API and are comfortable editing the API service calls directly, you might read how to integrate an existing service into the Intel XDK (and skip Using the Develop Tab below).

Using the Develop Tab

After you select the Develop tab, click Explore Services to show a list of third-party service providers:

	The toolbar appears under the row of tabs. One important button is Settings.
	You can either search for or view a list of web services available from third-party web service providers, or you can view and expand the list of third-party web service providers. As you explore and later save data bindings code, a list of saved data bindings appear under Saved Data Bindings.
	As you explore available web services, the right pane shows interactive details, such as search results and the API key(s) and parameters for a selected service. After you select a web service and obtain an API key (if needed), this area also displays JSON response data.
	In addition to exploring and selecting the listed third-party web services, this tab helps you integrate other third-party web services for your app. After you integrate and save web services data bindings code, the saved web services appear under Saved Data Bindings. You can click Create a New Web Service to integrate an existing web service.

To search for keywords within the web service names and their descriptions, use the button. For example:

1. Type a search string of forecast
2. Click the magnification icon to search
3. Click the button to view the search results
4. Click the name of the search result (such as forecast or wunderground) to expand that service under Explore Services
5. Under Explore Services, scroll to and expand Weather Underground* > Forecast.

For example, under Weather Underground* > Forecast, if click the name forecast:

To view the listed web services available from a service provider, click the button to the left of a web service provider's name. Consider which services you might use in your apps. For example, the screen below shows options under Weather Underground*. The chosen item name forecast, a short description, and its available methods appear in the lower-right part of the screen:

Once you select the service you wish to include in your app, you are now in the hands of the third-party service provider as explained later under Exploring Services. If needed, you can view their web pages or contact the provider for information regarding service costs, licensing, and technical help.

The high-level steps to use third-party web services include:

• Manage Account to obtain information about that service provider, including one or more API keys.
• Explore APIs to locate one or more APIs for your app.
• Embed the supplied <script tag references and JavaScript* code into your app. As you explore, you can save the code as data bindings you can later add to your app(s).

If you have code for an existing service and are familiar with calling web services, see Integrate Your Own Services.

Managing Accounts and Obtaining API Key(s)

Many web services require an API key. Register for a new account or access your existing account with the service provider to obtain API key(s). Your service provider may provide one or different API keys for different categories of APIs, and some web services do not require an API key. To register or access your existing account, click the Sign Up link to the right of the API Key field:

From the email or accessing your service provider account, type or paste each API key into the API Key: field and click the button. Once entered, the Intel XDK remembers your service provider API. To clear that API key, click Forget Key.

To select a web service under appMobi, you need to log into your appMobi* account and follow the displayed instructions.

Exploring Services APIs

After you provide an API key, you can now explore a set of web service APIs from this service provider. Feel free to explore and select a different subcategory in the left pane from that same service provider (if it uses the same API key).

After selecting a category:

1. View their descriptions, parameter name, type, and values. Type some likely parameter values. For example, select the USA Today* > Census > getLocations method in the left pane and enter parameters of a keypat state name of PA and a sumlevid of 3:
   
2. For information about these web services, click the button to the right of the method name.
3. Click the button.
4. View the retrieved JSON data under Response Body.
5. In the Response Body JSON data, check each box to select each data item to be included. Check the items in the first set of JSON data you want included in the output. If present, check any items you want included from the header. For example, these three items are checked so all sets retrieved in the RSS feed will contain this data:
   
6. Decide whether the parameter data you entered meets the needs of your app. You might need to modify parameter values and click the button again (or several times).
7. When the retrieved data under Response Body meets the need of your app, scroll down to thebutton. You can modify the name before you click this button. Skip to theSaving, Viewing, and Embedding Data Bindings Code section below.

If needed, consider these options after you view the retrieved JSON data:

• To view more details such as the API call, Response Code, Response Headers, and Response Body, click the button. Click this button again to erase the details.
• To close the service exploration area shown within the code editor window, click the button.
• To erase the Response Body results, click the button.

Saving, Viewing, and Embedding Data Bindings Code

To save the current API to later embed into your app, click the button. The Intel XDK remembers this value and saves its name in under Saved Data Bindings in the left pane. These saved data bindings are available your active Intel XDK project. Each Intel XDK project has its own set of data bindings associated with it.

At any time, open the Develop tab and under Saved Data Bindings, click a binding name to view the code relevant to that binding in the Develop tab Code view (see below).

View the JSON data. Scroll down to the button and click it. A dialog stating that you just created a data binding appears:

If you choose:

• Use in App Designer, the Develop tab shows the App Designer (Design interface). For example, you might use a list view widget to display the data retrieved by the web service.
• Open in Editor, the Develop tab shows the Editor (Code interface) including the generated web service code.
• No Thanks, the data binding is not created.

Use in App Designer

If you choose Use in App Designer, you can reference saved web service bindings within App Designer widget interfaces. In the in the upper-right corner of the App Designer GUI interface, view the Properties. For example, use the Service Method drop-down list to choose the service method name, use Data Array to choose the data array name for that service, and select web service parameters to be displayed from the displayed values.

For a video that shows how to use App Designer with an integrated web service, see http://software.intel.com/en-us/html5/videos/using-services-datafeed-in-app-designer.

Open in Code Editor

If you choose Open in Editor, the follow code appears in the Intel XDK built-in code editor:

View the code in the Develop tab. Note that the integrated service data bindings you create use wrapper names with a prefix of intel.xdk.services instead of the actual names used by the service provider.
After you open the data binding code in the editor, embed it into your app's code:

• Its required <script ... tags that you insert into a .html file. Select the generated code and copy (Ctrl/Cmd+C) the <script... tags near the top and paste them into your .html file(s). You may already have references to these definition files present.
• Review the JavaScript code and its comment lines. Select generated code and copy it into an existing or new JavaScript file. For example, view JavaScript code that:
  • Shows and uses the bindings as a promise or shows how attach them to an event handler.
  • Shows how to override the default input parameters that were set when you created the binding (near the bottom). You can modify the parameters and the parameter values.

For a video that shows how to use a listed web service, see http://software.intel.com/en-us/html5/videos/using-services-datafeed-in-brackets.

Viewing or Deleting a Saved Data Binding

Your saved data bindings appear under Saved Data Bindings in the left pane. At any time, click a name under Saved Data Bindings to view the data binding's JavaScript code. For example:

To close the window for now, click in the upper-right corner. To take further action, either:

• Click to delete that saved data binding. Its name is removed under Saved Data Bindings.
• Click and the code appears in the built-in code editor (see Open in Editor above).

Integrating Your Own Services

You can integrate your own previously created service for use in the Intel XDK. These three files help you integrate your web service:

• Edit the API Config File - The file apiconfig.json lists all the services defined for this project. It contains information common to all APIs within a given service, including a description of the service, the base URL for the service, and the authentication scheme. If the service utilizes any JavaScript libraries, those can be specified in this file as well. This file follows the format of iodocs from Mashery* (see https://github.com/mashery/iodocs). This file is required for integration into the Intel XDK.
• Create the iodocs File - This file, named yourservice.json, describes all of the endpoints and APIs within the service. This file follows the format of iodocs from Mashery (see https://github.com/mashery/iodocs). This file is required for integration into the Intel XDK.
• Create the js File - This file, named yourservice.js, links the methods listed in the above iodocs JSON file with the actual REST API calls of this service. You copy its script references into your index.html and copy its JavaScript code into other Intel XDK project files.

Here are the steps to create a new service in the Intel XDK:

• At the bottom of the left pane, click the button.
• Read the displayed instructions.
• Type a name for the service, without spaces.
• Click the button.
• Display the web pages from the service provider that describe the APIs side-by-side with the Intel XDK. To display these web pages, click the button to the right of the method name.
• Edit each of the three files created and replace the example placeholder values with relevant values. Save each file using the same name in the default directory. For example, when editing the JSON file, edit the code for parameters after comparing the placeholder values with the API web pages from the service provider. When editing the JavaScript file, make sure the information is consistent with any changes you made to the other files and also provide the API URL.
• Click the Develop tab button.
• Close and re-open the Intel XDK to begin using the web service.
• Submit your API key(s).
• Test the service call by clicking the button.

After you integrate and save web services data bindings code, the saved web services appear under Saved Data Bindings.

When editing the above files, observe these restrictions:

• Method names must not contain periods or blanks.
• An endpoint name must not contain these braces or square braces characters: ( ) and [ ].

If a service does not use authentication, omit the fields auth and keyparamfrom the apiconfig.json entry of that particular service.

If a service uses OAuth 2.0 authentication, read this article to add OAuth 2.0 authentication support: Using OAuth 2.0 Authentication for Certain Web Services. For example, some web services that need OAuth 2.0 authentication include web services provided by Foursquare*, Instagram*, and Twitter*.

If a service uses:

• No credentials, omit the fields apiKey and apiSecret from the apiconfig.json entry of that service.
• Only one credential, add the field “keyParam”: ”apiKey”. The value can then be accessed in the <servicename>.js file as the credentials.apiKey variable.
• Only two credentials, add the fields “keyParam”: ”apiKey” and “signature”:”apiSecret”. The values can then be accessed in the <servicename>.js file as credentials.apiKey variable and credentials.apiSecret.

To use a library in your service, add this field to the apiconfig.json entry:

"requiredLibraries": ["<link to library>"
     ]

You can add more than one library in the array.

For a video that shows how to create a web service not listed in the Develop tab, see http://software.intel.com/en-us/html5/videos/integrating-a-new-service.

Special Parameter Data Types

The “type” of a parameter is a string describing the variable type. There are two special types: Enumerated and Boolean.

• Enumerated type: For parameters that get values from a predefined set, use the enumerated type. This creates a drop-down box in the Develop tab GUI to allow exploring the predefined values. For example:

  "parameters": [
  {"Name": "leagues","Required": "N","Default": "cba","Type": "enumerated","EnumeratedList": ["nba","cba","qba"],"EnumeratedDescription" : {"nba":"nba description","cba":"cba description"},"Description": "abbreviation of league, such as mlb, nba, ..."
  },

• Boolean type: A Boolean parameter can be specified using the Boolean type. This creates a drop-down box in the Develop tab GUI to allow exploring the two Boolean values. Specify the default value for these Boolean values in the apiconfig.json entry for this service, using these fields: “booleanTrueVal”and “booleanFalseVal”(see below).
  These two fields can have the value of any of the Boolean derivatives depending on what the service API needs, such as: (‘true’,’false’,’T’,’t’,’f’,’1’,’0’, and so on). For example:
  
  In the .json file:

  {"Name": "disable","Required": "N","Default": "","Type": "boolean","Description": "if true; disables the categories parameter"
  },

  
  In the apiconfig.json file:

  "ESPN": {"name": "ESPN","description": "A great API","dashboardUrl": "http://developer.example.api","auth": "key","booleanTrueVal":"true","booleanFalseVal":"false"
  }

Services Settings

On the right of the toolbar locate these buttons:

Click the Settings button and click the Services tab within the dialog box:

Choose:

• Whether to optimize code you create for this project using the Develop tab which includes minifying your code. You might consider minifying your generated code (check this option), except when debugging (uncheck this option).
• A directory to contain your new service specifications for this project. The default directory xdk\services\iodocs is relative to the project root. To copy your new services for this project to another project, copy its contents to the other project's iodocs directory. To view your active project's path to your project root directory and source directory, click the Projects tab.
• A directory to contain code generated for saved Service data bindings. The default directory xdk\services is relative to the project source directory.
• To modify a directory path, click the button to choose a directory.

After you verify the current settings, click the button to save the settings.

Resources

• For information about the iodocs format from Mashery, see https://github.com/mashery/iodocs.
• This video shows how to use a web service listed in the in the Develop tab - click here.
• This video shows how to create a web service not listed in the Develop tab - click here.
• This video shows how to use App Designer with an integrated web service - click here.
• For information about using OAuth 2.0 authentication for certain services, see Using OAuth 2.0 Authentication for Certain Web Services.
• For an overview of the Intel XDK and its related software, access the Intel® Developer Zone at:  http://xdk.intel.com
• For a quick summary of the Intel XDK product and links to related documentation, see the Intel XDK Overview
• For information about using the built-in editor, see Using the Editor in the Intel XDK Develop Tab.
• For a short tutorial about using the Intel XDK development environment, see the Tutorial: Get Started with the Intel® XDK.