Watson now has a Spring Boot Starter to allow configuring Watson services using Spring annotations and properties.
This guide will show you how to use the Watson Spring Boot Starter to access a Watson service from a Spring Boot application. This example uses a Watson Discovery service on the IBM Cloud. You will perform the following steps:
- Create a Spring Boot application using the Spring Initializr
- Create a Watson Discovery service on the IBM Cloud
- Add the Discovery service config (credentials and URL) to your application
- Add the Watson Spring Boot Starter
- Add a REST endpoint that accesses the Discovery service and returns the results
- Build the app and invoke the REST endpoint and display the Watson service results
IBM’s Watson Discovery service makes it easy to build cognitive, cloud-based exploration applications that unlock actionable insights hidden in unstructured data.
- Maven and Java installed on your computer. It is assumed that you can build and run a Maven based Spring Initializr project.
- An IBM Cloud account – sign up if you don’t have an account yet
Create a Spring Boot project with the Spring Initializr
On the Spring Initializr page generate a
Maven Project with language
Java, and the
Web dependency. For this example we use group
com.example and artifact
watson-spring. Download the project and unzip it.
Create a Watson Discovery service using the IBM Cloud Catalog
On the IBM Cloud Watson Catalog select the Discovery service. The Lite version of the Discovery service is available to try for free.
Add the service URL and credentials to the app
Select the Discovery service on your IBM Cloud Dashboard select “Service credentials” in the left pane. If no credentials are listed, click the “New credential” button to create a set of credentials. Then click on “View credentials” to display the service credentials. Add the credentials to the
src/main/resources/application.properties file with the following property names:
watson.discovery.url=https://api.us-south.discovery.watson.cloud.ibm.com/api watson.discovery.username=<your-discovery-username> watson.discovery.password=<your-discovery-password> watson.discovery.versionDate=2018-3-14
versionDate value is not in the service’s credentials. You should set it to the current date in
Note: It is not recommended to store credentials in your application. We do so here only for the sake of simplicity in this tutorial. The Watson Spring Boot Starter can utilize other property sources such as environment variables, etc.
Add the Watson Spring Boot Starter, and a REST endpoint to invoke the Discovery service
For this example we’ll create a simple REST application with an endpoint that queries the Watson Discovery service for news items and returns a list of summary text for the matching news items.
Edit the unzipped Spring Boot project to make the following changes:
Add the following dependency in the
<dependency> <groupId>com.ibm.watson.developer_cloud</groupId> <artifactId>watson-spring-boot-starter</artifactId> <version>0.1.0</version> </dependency>
For the REST endpoint add a
@RestControllerannotation to the Spring Boot application class that was created by the Spring Initializr –
com/example/watsonspring/WatsonSpringApplication.java. (Note that the Java package and class names are derived from the Group and Artifact values entered on the Initializr).
- Add an
@Autowiredannotation for the
Discoveryobject. The Watson Spring Boot Starter will create the
Discoveryobject with the credentials found in
- Now add a REST endpoint with the
@GetMappingannotation to query system news. The method will:
- Accept a single
@RequestParamwhich will be the search argument for the Discovery service.
- Create a
QueryOptionsobject with the REST request query parameter, the environment ID “system”, and collection ID “news”.
- Use the
QueryOptionsobject and the
query()method to retrieve matching news items from the Discovery service.
- Extract the news item summaries from the
QueryResponseobject and return them to the caller.
- Accept a single
Your Spring Boot application should now look like the code below (shown here in the Intellij Idea IDE):
Build and run the app, and invoke the Discovery service
Build and run your app with the following command:
mvn package spring-boot:run
Now you can invoke the REST endpoint. In the example below we pass the query parameter
IBM+Cloud to search for new items about the IBM Cloud:
You should see output of current news items similar to this:
Try other query parameters to search for news on other topics!
The Watson Spring Boot Starter makes it easy to configure and use Watson services in a Spring native fashion using Spring auto configuration and Spring Boot properties.