Swagger for Domino Developers – Part One: Introduction
At IBM Connect I led a team for the Hackathon. Technically and in terms of meaningful outcome, the day was a bit of a disaster. In terms of learning and working together, it was still enjoyable. My main focus for the day was never to win. For me, the main aims were for the team to learn something, whether from one another or from the tasks and to have a good time. After all, everyone was giving up a day of their time, and if it’s not enjoyable, everyone would be best served spending their time elsewhere.
The difficulty was around collaboratively building an application around Domino. Without a Domino server that everyone had access to, it was a challenge. We struggled to easily set up Bluemix with Cloudant as the back end, because of different levels of access from the team. The application was API-driven, with a Swagger API built early on. But the challenge we hit was the back end needed creating for data to be available, for the front end to be built. And until the application was built, integration with e.g IFTTT and Watson Workspace could not be built, although investigation work could be done. We tried to work with a mock data service, so the back end was not a factor, but this too was something that we struggled with. In hindsight, building an application from scratch had logistical challenges which we were unable to overcome.
However, with the knowledge I since gained and experience I’ve since gathered, building an API-driven application would have been much more achievable.
Swagger has grown in prominence over recent years to the extent that it is not just a set of tools about how to build and develop against a REST service efficiently and effectively, the specification itself has changed its name to become more generic, as the OpenAPI Specification.
Priot to Connect I had worked with it to some extent with ODA Starter Servlet, for which I created JSON that could be imported into the Swagger Editor. I had also become aware of Stephan Wissel’s GitHub project, a Domino Codegen for Swagger, to generate the server-side stub for Domino.
At Connect itself, Swagger gained greater emphasis again with confirmation that the new REST services would have OpenAPI specifications published (and this has already been started on OpenNTF’s GitHub). SmartNSF is also focussed on delivering OpenAPI specifications for the REST services it generates. And Stephan Wissel’s session Beyond Domino Designer talked more about Swagger tooling as well.
In a world of application integration, if you’re providing standard REST services in youor Domino applications for integration, publishing OpenAPI specifications for those REST services is best practice, will demonstrate Domino developers are embracing standards beyond the yellow bubble, and better document integration points for external developers integrating with Domino data. And providing better integration with Domino data helps stave off talk of migration and ill-informed arguments that “Domino can’t do that”.
Just to clarify a couple of points here. Firstly, like any other documentation framework, an OpenAPI specification can be good or bad. For example, showing your API takes a string or a number is useful only if you have details or examples that clarify what the string or number should be. Secondly, an OpenAPI specification only handles standard REST services. Anyone who attended my session at IBM Connect, which will be repeated at Engage in May, will know I am also a fan of GraphQL. GraphQL publishes its own schema and has a different documentation and testing method, as anyone who’s dug into Watson Workspace will be aware.
In the rest of this series I’ll cover setting up the Swagger editor, an overview of the Domino Swagger Codegen, and how to set up a mock server to develop against and persist data. If you’ve done a lot of development with Node.js, a lot of this will need little introduction. But if your work has been solely in Domino Designer or your focus has been Java and XPages, there is a lot that’s new and – in my case at least – left me stumbling around a bit at times and relying heavily on Stephan Wissel’s support. So it’s right to blog it, if only as future reference for myself and to help reinforce and clarify the notes I made at the time.