Bootstrapping the adoption of new technologies is always a challenge. Coming up to speed is easier when you can experiment with and explore a user interface, but getting started with REST APIs, like the REST APIs that comprise the Watson Developer Cloud (WDC) services, often requires more information. Getting started with APIs usually requires detailed documentation, easy access to sample code, and an active community where you can ask questions, and expect to get answers. All of these tools are available for the Watson Developer Cloud services. Navigate this list for more information and links to these tools:

Client-Side libraries in GitHub

Quick links:

REST APIs provide platform and language independence by using HTTP as their transport mechanism, simplifying remote API access by using HTTP verbs to support standard create, read/retrieve, update, and delete (CRUD) operations. Using standard GET, PUT, POST, and DELETE HTTP verbs to provide these basic operations can provide clear, readable, and more easily maintainable code. However, building more complex actions from low-level operations also means that more code is required for complex tasks because the API does not natively support any higher-level operations.

Like many services that use REST APIs, the Watson Developer Cloud services provide client-side libraries that support higher-level operations. Often referred to as SDKs or “wrappers”, these libraries are available for all WDC services, are freely available on GitHub, and are open source under the Apache 2.0 license. Client-side libraries for the WDC services are currently available for developers who are using Node.js and Java:

  • The node.js wrapper is provided as the watson-developer-cloud npm module that you can install permanently by using the “npm install watson-developer-cloud” command or dynamically include in your projects by using the Node.js “require” function.
  • The Java wrapper is built into a JAR file that you include as part of your project. You can either build the JAR file yourself, or download it as part of the latest “JARs with dependencies” package from the Release link on GitHub. This archive contains the Java wrapper plus other open source class files that it requires.

As an example of the advantages of using client-side libraries, the following Node.js code uses the Watson Text to Speech service’s wrapper to speak the words “Hello, World”:

var watson = require('watson-developer-cloud');

var text_to_speech = watson.text_to_speech({

 user name: '{user name}',

 password: '{password}',

 version: 'v1'

});

text_to_speech.synthesize({text:'Hello World'}, function(err, res) {});

These two declarations and one function call replace all of the work that is traditionally required when using the Speech to Text REST API: configuring the URL to the service, extracting and using the right portions of Bluemix environment variable that contains user information, calling the appropriate method to synthesize text, and so on.
In order to use this snippet, replace the ‘{user name}’ and ‘{password}’ entries with the values that you received in Bluemix after binding your service instance to your target application. To see the credentials for an instance of a service, select the Dashboard view in Bluemix, select the application to which the service is bound, and:

  • To see the credentials for all services that are bound to the application, click “Environment Variables” in the left navigation menu, then click VCAP_SERVICES. You can then scroll down to see the user name and password credentials for a specific service, which is used by that application.
  • To see the credentials for a particular service, click “Show Credentials” on the tile for that service

In Java, you supply the user name and password after creating a new service object to contain the information about a service in your application, and then using service.setUsernameAndPassword(“user name”, “password”) to set the values of those fields.

Sample source code in GitHub

Quick links:

The wrappers that were discussed in the previous section make it easier for you to write code, but don’t provide a “big picture” of developing a complete application by using a WDC service. Seeing complete applications that use wrappers are useful for more complex scenarios than calling one or two methods. Seeing complete applications that natively use REST APIs is similarly useful if you are working in a language for which no client-side library is available.

Like the wrappers, the source code and build configuration for many sample applications for the WDC services are available in GitHub. The sample applications are all open source, and are released under the Apache 2.0 license. While most of the sample WDC applications that are provided in GitHub are in the primary languages that the WDC services support, like Node.js and Java, sample applications in languages such as Ruby and Python are also available there.

Providing sample application code in GitHub is not a read-only function. The sample WDC code there has already benefited from contributions by the WDC community, and we’d appreciate your contributions, too. Like all GitHub projects, you can submit corrections, stylistic suggestions, or enhancements by forking any of the existing WDC GitHub repos, making your changes, and submitting a merge request.

Beyond just enhancing existing sample code offerings that are already available in GitHub, we also encourage developers to contribute sample application or wrapper code in other languages, additional sample applications in any language, and so on.

WDC Services communities

Quick links:

If all of your friends are working on the same sorts of applications that you are and are using the same technologies, I envy you. You already have a community where you can ask questions and expect useful responses and suggestions. Unfortunately, most of the rest of us require websites, forum, or other online mechanism where we can submit questions and hope for useful responses from people who have more experience with the technologies.

The WDC services have a dynamic and involved community in IBM’s developerWorks Answers (dWAnswers) forums. The dWAnswers forums are a huge pool of questions and answers that are differentiated by the metadata with which they are tagged. Because the WDC services are hosted in IBM’s Bluemix cloud computing platform, all WDC-related questions should at least be tagged with both the WATSON and BLUEMIX tags. However, Watson is much bigger than just the WDC services – there are many other Watson-related projects, such as Watson Engagement Advisor, Watson Discovery Advisor, or the Chef Watson application. To increase the likelihood of someone answering questions about a specific WDC service or an application that uses a service, you should also tag your question with the tag that is associated with the service(s) that you are using. Service-specific tags consist of the capitalized name of a service, with each word in the name of the service that is separated by a hyphen (for example, “PERSONALITY-INSIGHTS”). We’ll get back to you – or someone other community member will!

While the dwAnswers forums, and IBM developerWorks in general are popular on the web, those resources might not be the first place that people think of asking questions or looking for answers. It’s easy to find information on developerWorks via your favorite search engine, but we also want to make sure that questions and answers live in common resources where people might go to directly – most notably StackOverflow. Both the Bluemix and WDC services documentation encourage users to post as many of their questions as possible on StackOverflow to ensure that questions and answers are available in resources that people might consult directly or by default. After all, why use a search engine to find something when you already know where to look for it? Because different online question-and-answer forums have different user communities, with different rewards for participation, some knowledgeable users might prefer one over the other. We don’t – we want you to get the answers that you need in order to make your use of the WDC services as quickly and efficiently as possible.

On StackOverflow, tag questions that are related to the WDC services or any other Watson-related technology with the “ibm-watson” tag. Asking Bluemix or WDC-related questions in as many places as possible gets you the attention of a wider community of experienced users, and help increase the speed with which you can hope to receive a response.

WDC Docs

Quick links:

Sample code is a great way to see how to construct an application, but doesn’t answer general questions like what WDC services are available and the benefits that each of them can provide in your applications. Neither the sample code, or an online community is the correct place to look for general, per-service questions, like what the inputs and outputs of a service are, whether the service is free or costs money, or where to find an online demonstration of a service. For general and service-specific questions, first look in the WDC documentation. (You can always ask questions in a forum if the docs don’t answer your general questions.) The WDC documentation provides different entry points for different audiences and types of questions:

  • Services Catalog – available in the header on each page of the WDC documentation, the Services Catalog contains icons for each WDC service. These icons link to high-level, introductory information about that service. This introduction includes a quick description of the service, links to online demos for that service which are always available, general information about inputs and outputs, and a link to the documentation for that service.
  • Docs – also available in the header on each page of the WDC documentation, the Docs link contains icons for each WDC service. These icons link directly to the documentation for the associated service, which provides detailed information about each service, such as a discussion of common use cases for a service, the inputs that each service requires, and how to interpret and use the output of each service. The documentation also includes links to reference material for each service, and links to sample applications for that service in Node.js and Java along with an explanation of how to build and deploy that sample code. The documentation for most WDC services also includes information about the research that contributed to the development of each service, published papers about that research, and so on.

Conclusion

Developing applications for business, academic, or general learning purposes is simplified by a robust ecosystem of supporting resources, including sample code and easy-to-use client libraries, online resources where you can ask questions and get answers, and detailed, accurate documentation.

Yesterday’s products often walled off much of that information, limiting it to paid customers or active prospects. Today’s products live in a much more open and collaborative universe, where all of the information that you need to use a product or to resolve more detailed or esoteric questions is freely available on the net. After continuous availability, the best aspect of open, public resources like GitHub, dWAnswers, and StackOverflow is that they are not limited to an existing community of expert contributors. Today’s novices can easily become tomorrow’s experts by participating.

I look forward to seeing you there!

Join The Discussion

Your email address will not be published. Required fields are marked *