Web Services Overview

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 listed third-party web services, you can 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.

Note: The collection of web 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. You are under no obligation to use the web services provided by this feature - you may use any web services that are appropriate for your app. Please contact your third-party web services provider(s) for information regarding service costs, licensing and technical/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.

To give your app the permissions necessary to access external web services you must configure your app's Domain Whitelist in the Build Settings section of the Projects tab. Please see Cordova Whitelisting with Intel XDK for AJAX and Launching External Apps for details.

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 your app.
  • 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 below (and skip the section Using the Develop Tab to Explore and Integrate Web Services immediately below).

Using the Develop Tab to Explore and Integrate Web Services

After you select the Develop tab, locate the Web Services in the lower-left corner. 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. Press Enter or click the magnification button to search.
  3. To specify a different search string, you can hide (or view) the results of your previous search by clicking the button.
  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 Weather Underground* > Forecast.

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

To view the web services available from a service provider, click its name or 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 below 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 explained below 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 below.

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:

Obtain the API key from the email or by 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 data 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 data 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 several times.
  7. When the retrieved data under Response Body meets the need of your app, scroll down to the button. You can modify the name before you click this button. Skip to Saving, Viewing, and Embedding Data Bindings Code 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 examine the web services code in a debugger, click the button. The debugger is similar to the Google Chrome Development Tools debugger. See Using the Debugger below.
  • 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 to and click the button. A dialog stating that you just created a data binding appears:

If you choose:

  • Use in App Designer, this option is no longer supported.
  • Open in Editor, the Develop tab shows the Code Editor including the generated web service code.
  • No Thanks, the data binding is not created.

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:

  • Copy required <script ... tags that into an .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/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 Code 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. Copy the applicable script references into your index.html and copy its JavaScript code into other Intel XDK project files. You might launch the debugger ( button) while writing this file.

NOTE: the precise format of the JSON files required by the Intel XDK web services may not be completely consistent with the current schema defined by the I/O Docs API-Level Config Details, because it is based on an earlier version of that specification.

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. To examine the web services code in a debugger, click the button (see Using the Debugger below).
  • Click the Develop tab button.
  • Close and re-open the Intel XDK to begin using the web service.
  • Submit your API key(s).
  • You can test the service call by clicking the button.

After you integrate and save web services data binding 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 keyparam from 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/videos/integrating-a-new-service.

Using the Debugger

You can use the built-in debugger to run and debug your web services code. The debugger is based on and its use resembles the standard Chrome Developer Tools (DevTools) debugger (similar to the Intel XDK SIMULATE tab). To show the debugger, click the button.

The debugger appears in a floating window. You can type commands into a Console and view Sources, including inserting/removing breakpoints (or insert a breakpoint; statement). For example, you can click the Sources tab and press Ctrl/Cmd+O to examine the generated script files. The debugger screen cap below shows the file api-request-common.js, which contains generated merged code of the jsdocs files for all known services:

Although the debugger lets you view your source code, modifying sources in the debugger does not modify your source code in your project files. You can copy source code from the debugger Sources tab to your project files. For information about using the debugger, see https://developers.google.com/web/tools/chrome-devtools/debug. To close the debugger, click the red x in the upper-right corner.

Special Parameters

NOTE: These "special parameters" are only used by the Web Services UI component of the Develop tab. They do not impact the JavaScript that parses the JSON data objects that are used to manage your custom web service.

There are two special parameters: Enumerated and Boolean.

  • Enumerated: indicates a list of predefined values. This creates a drop-down list in the Develop tab GUI containing 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: indicates a list of two predefined values. This creates a two-item drop-down list in the Develop tab GUI containing the predefined Boolean values. You specify those Boolean values in the apiconfig.json entry for this service, using these fields: "booleanTrueVal" and "booleanFalseVal". These two fields can have the value of any of the Boolean derivatives depending on what the service API needs, such as: 'true' and 'false' or 'yes' and 'no' or '1' and '0' and so on. For example:

    In the .json file:
    {
       "Name": "disable",
       "Required": "N",
       "Default": "",
       "Type": "boolean",
       "Description": "if true; disables the categories parameter"
    },
    And in the apiconfig.json file:
    "ESPN": {
    "name": "ESPN",
    "description": "A great API",
    "dashboardUrl": "http://developer.example.api",
    "auth": "key",
    "booleanTrueVal":"true",
    "booleanFalseVal":"false"
    }

NOTE: the mechanism described above is not completely consistent with the current schema defined by the I/O Docs API-Level Config Details, because it is based on an earlier version of that specification.

Services Settings

On the right of the toolbar locate these buttons:

Click the Settings button and click the Services tab within the dialog box:
Services Tab settings
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 Browse button to choose a different directory.

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

Resources

For more complete information about compiler optimizations, see our Optimization Notice.