Use the Watson Spring Boot Starter to access Watson services

Watson now has a Spring Boot Starter to allow configuring Watson services using Spring annotations and properties.

Learning objectives

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

Estimated time

One hour.


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.


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/ file with the following property names:


Note: The versionDate value is not in the service’s credentials. You should set it to the current date in yyyy-mm-dd format.

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 pom.xml dependencies section:

  • For the REST endpoint add a @RestController annotation to the Spring Boot application class that was created by the Spring Initializr – com/example/watsonspring/ (Note that the Java package and class names are derived from the Group and Artifact values entered on the Initializr).

  • Add an @Autowired annotation for the Discovery object. The Watson Spring Boot Starter will create the Discovery object with the credentials found in
  • Now add a REST endpoint with the @GetMapping annotation to query system news. The method will:
    • Accept a single @RequestParam which will be the search argument for the Discovery service.
    • Create a QueryOptions object with the REST request query parameter, the environment ID “system”, and collection ID “news”.
    • Use the QueryOptions object and the Discovery object’s query() method to retrieve matching news items from the Discovery service.
    • Extract the news item summaries from the QueryResponse object and return them to the caller.

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.