Ensuring a high-quality user experience is at the very core of our work at Documill. So recently, when working on another new Documill service, we set as a target to make it as easy as possible for external developers to seamlessly integrate our service as an embeddable component directly to the user interface (UI) of their service. This would save the end users from any context-switching (or application hopping) when using a service – an annoyance, whose importance we have earlier discussed here .
The transparency and clarity of the definition of the application programming interface (API) plays a crucial part here. So let’s say there is service provider, who would like use our document previewing functionality fully embedded in their own service. We strive to ensure that any developer could quickly get a clear idea of what our service does and how it can be used, down to its operations (or methods) and the parameters they accept for adjusting them.
Achieving this would mean that, at our end, definition of the application interfaces (APIs) would come first, even before implementing our own service.
Furthermore, in the API design and definition, we wanted to stick to the RESTful approach, so we could also ensure:
- freedom of service design for connected components and applications
- service scalability
- high performance of applications, especially through minimized latency
- that utilization of our service as a component of another service is as easy as possible.
One clear API definition for all users with Swagger
So, we decided that there would be just one, clear API definition that both our internal and the external developers could rely on and refer their code to.
But how should such an API then be defined in practice? For starters, documenting every method and parameter manually was quickly ruled out simply as too laborious and error-prone.
After a bit of contemplation and research, we came across the Swagger definition format. It looked promising, as it seemed to allow creating a clear, concise, yet comprehensive representation of our API. Also, the suite of tools supporting it, such as swagger-ui, would make it possible to also produce interactive documentation for the API.
The Swagger representation is essentially an API definition in a specific JSON format (swagger.json), in the form of human-readable text. It can be generated either manually or by a machine, which makes it suitable for any technology within the scope of RESTful API design. So Swagger became our choice.
Machine-based creation with Swagger-Core and JAX-RS
The next step, then, was to find the tools for generating the Swagger-format API definition directly from the code that would actually implement the API, without unnecessary manual work. After a little bit of search and
evaluation, we settled at the Java implementation of Swagger called Swagger-Core, coupled with the JAX-RS Java API.
They would allow us to have a single definitive place in our code for each of the resources (for example, documents and sessions), which define the API. The code in these resources is kept minimal, only doing what is necessary to forward the appropriate parameters to the more complex code that implements the services.
Mission accomplished: RESTful API for maximized user experience
This layer of JAX-RS resources, decorated with Swagger-Core annotations, has served us well in separating the API definition, which needs to be stable, from the actual implementation, which can change significantly without affecting the API.
At the end of the day, it provides a sound basis for designing a sticky service that really pleases the users – and generates successful business.