JSight – Why did we not go crazy when we decided to create one more language?
We didn't come up with the idea to create a new language for describing the REST API from scratch. Generally speaking, extremely compelling reasons are required to make such a hard decision as creating a new language and being of sound mind. And there were valid grounds for us to do so.
We’ve been working together for a long time and have completed several dozen IT projects of varied sizes. In almost all projects, we’ve used the REST API in some form or another. We only wanted one thing. Very simple. We wanted to keep our REST API documentation up to date. And that's all. Nothing more!
It turned out to be a challenging task. We won't go over every solution we’ve tested. We'll try to put things in order in the next posts. Initially we tried to describe our API simply in the Wiki. Thereafter, we tried to describe the API using special languages (Swagger, RAML, API Blueprint, etc.). We tried to describe the API right in the code using annotations, followed by auto-generation of documentation. We tried to keep the documentation up to date with soft and hard administrative methods. At some point, we even “fell back” to SOAP and WSDL – imagine the level of our despair!
Let's not say that we were unsuccessful. Life moved on in some way. However, there was a nagging feeling inside that somehow it should be done in a different way.
We realized that there is only one way to automatically keep API documentation up-to-date – to embed the documentation directly into the code, forcing the code to work strictly in accordance with the documentation. Many have chosen this path (WSDL, Thrift, gRPC, etc.). So what prevented us from going the same way?
The answer was simple. None of the existing languages for describing API appealed to us. Modern languages, such as OpenAPI (Swagger), are, of course, far more convenient than the old monstrous WSDL. And yet, for a developer or technical writer, explaining a medium-sized API on Swagger turned into several thousand lines of misery. As a result, no matter what approach we used to keep the documentation up to date, the documentation procedure itself was still there to be done. Someone at some point still had to sit down and, with an expression of inexpressible suffering on his face, fix the documentation in one language or another. Detailed documentation was met with hushed but unanimous opposition from the team. So many project managers gave up under this pressure and turned a blind eye to the documentation. In short, API documentation has been a constant struggle.
Then it hit us. We immediately realized how to describe API in a much simpler way than what OpenAPI, RAML, API Blueprint, WSDL, GraphQL, Protocol Buffer, and many, many other languages offered.
Our idea was both amazingly simple and surprisingly effective! Describing the API has become enjoyable rather than painful. The speed of writing and changing documentation has increased several (!) times, but the important thing is that our employees now enjoy it!
Based on our idea, we created a new language and named it JSight.
Dear friends, sorry for the intrigue. Please be patient! In the coming months, we will share our idea, publish a detailed description of our language, and provide free tools for working with it.
Follow the news!