As I’ve blogged before, over recent weeks I’ve been working with Christian Guedemann on a Java SDK for the Watson Work Services API. The documentation has been available since it was released at the end of October. There has also been a GraphiQL in-browser IDE for writing, validating and testing GraphQL queries against Watson Work Services, which is invaluable (note: you have be authenticated to Watson Workspace in the same browser for the queries to return any data).
That also has a documentation explorer available by clicking the “Docs” link in the top-right of the IDE (easily missed, I did!). This is available because GraphQL not only defines a schema for queries and mutations, it also provides a query for introspecting the schema. This has drill-down to the QueryRoot that allows you to see all the queries available. Obviously, if you’re building a Java SDK for building those queries, it’s critical to know what queries are available, and which attributes are available as arguments for filtering the query and whether they are mandatory.
But sometimes it’s useful to see all of that in a single diagram. Fortunately, Nathan Smith has created a visualisation tool for any GraphQL schema (thanks, Miguel Estrada for telling me about this). There are just two easy steps. First copy the Introspection Query at the top of webpage, paste it into the GraphiQL IDE and process it to get the result. Then copy that result and paste it into the Introspection Result textbox on the webpage. You then get a downloadable image showing the entity relationship diagram for the GraphQL queries, as below. (Because of the layout, I would recommend running it yourself and downloading the image, so you can zoom in on various areas.)
On the topic of the SDK, we’ve now finalised all the QueryRoot builders for the GraphQL endpoint (“https://api.watsonwork.ibm.com/graphql”) as well as including an endpoint to post messages to a space (“https://api.watsonwork.ibm.com/v1/spaces/{spaceId}/messages”). That is due to be published over the next few days as version 0.5.0 on Maven Central. There have been some minor amendments since my last blog post, the possibly breaking change being a separate set of enums for adding attributes to filter the query on. This is because not all properties of the underlying object can be used to filter a query. But the biggest impact is a set of helper methods to pass an instance of BaseGraphQLQuery
directly to the WWClient
. This removes a need to interact with the GraphQL endpoint, so fewer lines of code. If you’re not interested in refining the default fields and children we’re returning, there are also methods directly available from the WWClient
(e.g. WWClient.getSpaces()
, WWClient.getSpaceById(String)
etc) to give even easier access.
One of the main aims from the start has been test-driven design, so there are a number of JUnit tests run as part of the build process. The maven build process also generates Javadocs in target/apidocs folder of the wws-api project. I’ve also posted those Javadocs for easy access. Now 0.5.0 is ready, I also intend to add some documentation on OpenNTF’s Confluence site.
There is still work to do, which will continue in 0.6.0, for the mutations as well as additional endpoints like “https://api.watsonwork.ibm.com/v1/focus” and “https://api.watsonwork.ibm.com/v1/photos”.
The API SDK, and Watson Work Services / Watson Workspace in general, will be covered in my session with Christian at IBM Connect in February, GraphQL 101.