Using the Services Tab

The Services 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 Services tab helps you integrate other existing web services, such as those developed specifically for this 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.

Some examples include using a database service, app cross promotion, and analytics.

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. Use your account to obtain API key(s) for selected services available from each service provider.

When to Use the Services Tab to Integrate a Service

The Services 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, you might skip using the Services tab if you already know the chosen web service API and can are comfortable editing the API service calls directly.

Using the Services Tab to Integrate a Service

After you select the Services tab, a list of third-party service providers appears:

	The toolbar appears under the row of tabs. The important buttons include Reload (left) and Settings (right).
	View a list of third-party web service providers and explore the web services they provide. As you explore and later save data bindings code, a list appears under View Saved Data Bindings.
	As you explore available web services, the right pane shows interactive details, such as the API key(s), parameters for the selected service, and 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 View Saved Data Bindings.

To view the listed web services available from a service provider, click its name or the button to the left of its name. Consider which categories or services within a category you might use in your apps. For example, the screen below shows Rotten Tomatoes* as the chosen provider. The available categories (such as Movie Lists) and methods within that category (such as opening) appear below the service provider's name:

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 under Exploring APIs . 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 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).

Managing Accounts and Obtaining API Key(s)

With most service providers, access your account to obtain API key(s) from the service provider. Your service provider may provide one or different API keys for different categories of APIs. To register for a new account or access your existing account, click the Sign Up link to the right of the API Key field:

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 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 > Census > getPopulation 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 a box to select a 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.
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 the button. 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 redisplay the initial screen in the Services tab, click the button in the toolbar below the Project tab.
• 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 View 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 Services tab and under View Saved Data Bindings, click a binding name to view its required script tags and related JavaScript* code.

View the JSON data. Scroll down to the button and click it. A dialog stating that you just created a data binding appears. Dismiss it. The generated web service code now appears:

After viewing the code, do one of the following:

• Click the button. The web service code appears in the Intel XDK editor in the Develop tab.
• Click the button to delete that saved data binding. Its name is removed under View Saved Data Bindings.
• View the code but do nothing now, which leaves the binding available for later use.

When using the Services tab, 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:

• 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. For example, the code near the bottom provides the parameters and the parameter values. If needed, you can modify the values.
• Select other generated code and copy (Ctrl/Cmd+C) it. Paste it into an existing JavaScript file or into a new file.

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.
You can also reference saved web service bindings within App Designer widget interfaces. In the App Designer GUI interface, view the Properties in the upper-right, such as selecting a Service Method (method name), selecting a Data Array, 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.

Integrating Your Own Services

To use a web service not listed in the set of APIs listed in the left pane, you need to integrate your own service. These three files help you integrate your own 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 Service tab:

• 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 Services tab button.
• Click the button 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 View Saved Data Bindings.
For a video that shows how to create a web service not listed in the Services tab, see http://software.intel.com/en-us/html5/videos/integrating-a-new-service.

Services Tab 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 Services 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.
• For a video that shows how to use a listed web service, click here.
• For a video that shows how to create a web service not listed in the Services tab, click here.
• For a video that shows how to use App Designer with an integrated web service, click here.
• 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 and Documentation Page
• 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.