One of the biggest challenges of creating a new language is balancing “Power” and “Simplicity”.

By “simple” language, we mean a language with minimal rules.

By “powerful” language, we mean one that allows you to elegantly solve a wide range of problems. “Powerful” language is convenient, concise, and readable.

At first glance, there appears to be no clear contradiction between “power” and “simplicity”, but try creating a new language and you will immediately understand this dilemma!

Here's the thing: in order to make a language more powerful, we must increase the number of rules – that is, increase its “complexity” or, in other words, decrease its “simplicity”.

For example, let's take arithmetic. Assume we only have one addition operation. Then we can write “2 times 5” as “2 + 2 + 2 + 2 + 2”. It's simple, but not elegant. Now let’s introduce a new “rule” – the multiplication operation. We can now write it like this: “2*5”. It turned out much better, but we lost the simplicity because we added a new rule.

The dilemma is that a “simple” language is much easier to learn, whereas a “powerful” language is much easier to live with. The more powerful a language becomes, the more difficult it is to attract new users. However, the more simple our language is, the more our users will be disappointed when trying to solve complex problems while using it.

It is unlikely that a formal algorithm could be developed to help resolve this issue. It seems that the search for the right balance appears to take place somewhere in the realm of intuition and subconsciousness. So far, we've relied on instinct while developing our language.

The first version of the language will be released soon! Shortly after the release, we will share some interesting cases where we had to painfully choose between “power” and “simplicity”. We guarantee that when developing new versions of the language, we will involve our users in resolving such issues, and we will definitely take your feedback into account.

Welcome to the world of JSight!

During the conversation on the phone with a potential customer, I was telling the story of our project:

"... and in so and so year, we decided to create a tool so that the REST API documentation for our projects is always up-to-date..."

And at this moment, from the other end of the line, I heard like an animal snarl, overwhelmed with anguish and hope:

"Yesssssssss!!!!!"

Friends, I can't express how much suffering and understanding I heard in that sound.) There are some things that can't be described in words. After that, we both burst out laughing.

A potential customer is in charge of a big project at the world's largest telecommunications company. The peculiarity of their REST API is that they return massive JSON-structures in response. (In JSON format, a description of a cell operator's tariff can take several hundred thousand lines). And, of course, any error in the documentation is fatal.

It looks like JSight is on the right track. Follow the news, the release is soon!

We came across an unusual scenario the other day, which, on the one hand, amused us a lot, while, on the other hand, once again confirmed the problems connected with the accuracy of API documentation.

One of our third-party advisers discussed their experience of work with external REST API.

In their projects, they frequently use external REST API services provided by various large companies (Facebook, Instagram, VKontakte, etc.). Unfortunately, they are frequently confronted with the fact that the official documentation for the external API does not correspond to reality. Developers are irritated when an endpoint returns incorrect or incomplete data that was specified in the document.

So, some time ago, the company decided that they would now WRITE THE DOCUMENTATION FOR EXTERNAL SERVICES BY THEMSELVES! And, what's more interesting, they got right to work: they now write and support documentation for third-party services by themselves!

Imagine the absurdity of the situation. A large company (for example, Facebook) publishes an external REST API and provides it with detailed documentation. Developers and users of this service find flaws in this documentation and find out that the REST API actually works a little differently, which is why they are constantly having integration issues. So, in order to avoid stepping on this rake over and over again, they devote all of their time and effort to create their own internal version of the documentation for the external service API. Well, that’s how much you can annoy the developer with the inaccuracy of the documentation!

You don't know whether to cry or laugh, as they say. This is, however, good news for JSight. This means that our experience is relevant, that it is not in vain that we are fighting first and foremost the ACCURACY of the documentation, not forgetting, of course, about the convenience for developers. The first version of our free tool will be available soon! Don't miss out on the chance to be one of the first to try JSight!

That's funny!

We’re almost ready to release the first tools for working with JSight, and we’ve started documenting them in our own JSight language. It turns out that we’re doing JSight using JSight :)

We’ve all heard before that the first thing developers do after creating a compiler for a new language is rewrite it in the same language. We now understand that this is not a joke.

The experience of designing an internal API in JSight was once again successful and even surprising. We hoped that by creating the language, we would be able to considerably simplify two processes: describing the API and reading the already described API. But we had no idea that JSight would be pretty useful for the third process – API design! Yes, in our language, it turned out to be more convenient to design an API from scratch. The language helps you think in terms of API, quickly sketch out visual API prototypes, erase, rewrite, compare, and so on.

Designing an API from scratch in other languages is really tough. We tried)

It's too sad we can't share the details with you right now! We have decided not to divulge key concepts until the first release which will be soon. We will share all the details after the release.

Subscribe to our channel to stay up to date! Will be released soon!

Hello everyone!

We recently tested our language on the Instagram public API. Using JSight, we tried to completely describe the Instagram Graph API. We used the official Instagram docs to do so: Instagram

By the way, Instagram Graph API is one of the ten most popularly used API on our planet.

Our language was successfully able to do the task! We had to use almost all language constructions that we came up with, even those that initially seemed not very much in demand.

Furthermore, in certain instances, the JSight language has shown itself unexpectedly. With the use of constructs that were initially created for other purposes, we were able to neatly overcome some of the problems. On the one hand, this shows that we are still new with little experience in working with our own language:) On the other hand, it once again confirmed that we are on the right track.

We discovered certain flaws in the official Instagram API documentation while working with it. We found several gaps and contradictions (stylistic and even logical). If the Instagram API was described using our language, and not manually, these errors could probably be avoided.

It's interesting to describe the Instagram API using Swagger and compare the generated code with the JSight version. Watch our channel for the comparison results!

I've recently heard from a number of people that gRPC is on the rise, and that it may eventually supplant the standard REST API. Such a thesis astounded me greatly. I'd like to offer some thoughts on this.

First, let's talk about the market's current state. We analysed several different sources – various studies in well-known periodicals, search query statistics, and the number of likes and mentions on various portals – and then came up with some preliminary findings. Approximately 80% of the total number of API worldwide were created using HTTP REST technology. We estimate that gRPC technology is used in less than 1% of all API worldwide. So it’s still far too early to talk seriously about a global trend in changing technology.

On the other hand, we can discuss the rise in popularity. Indeed, interest in gRPC technology is increasing rapidly, at least three times faster than in the previous two years. However, interest in HTTP REST is also growing, albeit at a slower rate (about 30 percent per year). As a result, it’s incorrect to assert that gRPC is "taking away" a portion of the market from REST. It’s more accurate to say that the API market in general is expanding rapidly in all directions.

And finally. In principle, it’s incorrect to consider gRPC and HTTP REST as competitors. These are quite different technologies that address different issues. We'll compare the two in more detail in future posts. Let us now go on to the most significant point. HTTP REST is the cheapest technology. The REST entry threshold is set to the bare minimum. Employees are just required to have a basic level of qualification. Working with REST is extremely convenient. The dangers are minor. REST's only significant disadvantage is its slow data rate. gRPC – technology is more expensive to develop and maintain. The entry threshold is significantly higher than in REST, as are the employee qualification requirements. The main advantage is the high speed of data exchange.

As a result, if the API does not require high performance, people prefer cheap and simple REST. If the API has stringent requirements, it makes sense to fork out on the gRPC. Obviously, the former will always be several times more than the latter.

We worked on a project on the PHP Symfony with API Platform. This is pretty popular for API. As documentation, there was a bundle that generates OpenAPI docs from code. This seems very natural for developers, since most of the API is described declaratively in the annotations to the primary entities, and the bundle generates documents based on these annotations. In this way, documents represent what is in the code. But not vice-versa.

And so we discovered that some methods collect and return data that is not required by the front end, while also substantially loading the back end. We make the decision to remove this data from the particular method. In the framework, serialization groups are used to do this: labels are put on each field of the object to indicate in which contexts it should be issued. This all gets confused very quickly by haphazard grouping; therefore, we lost part of the valuable data while removing the unwanted data. Then we started to retrieve the lost data. We can discuss the details of the framework for a long time here, but in short, a few commits and a deployment on tests later, and we’ve a situation where the methods return an incomplete set of data, and no one knows exactly which one is complete. And the documentation shows not what should be, but what is now in the code.

And this is what we were left with:

• Edit data based on logic, but logic only applies to a certain area, whereas data is used in numerous areas. You dominate one place with logic and break two others. In the end, the testers are responsible for everything.
• Look at the front code. It could be one of them. It’s infested with bugs and does not inspire complete faith. Furthermore, you must divert the attention of the front-end developers. And the same issues as mentioned above.
• Checkout revision when we’ve not yet removed unnecessary data. However, because the application has a variety of logic, one dataset may have a slightly different appearance. So you need to look at different cases with full-fledged data and remove the structure from there. Also, keep in mind that this is initially a faulty code that we actually took to edit.

It’s clear that all of these alternatives are clearly cumbersome, unreliable, and inefficient in terms of labor costs. There was no other choice. And all that remained was to modify and test.

API documentation should be included in the design and the JSight project will finally overcome this problem.

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!

The development market is growing and the number and complexity of API is increasing.

Corporates are eager to implement new solutions to boost the productivity of their R&D department. The software development industry, as a whole, is moving towards simplicity and human-centered solutions. These factors have prompted us to revolutionize API documentation. It's time to turn things around and create a whole new approach. We’ve invented a new language for describing API. It's not just “another language”. It fundamentally alters all principles that describe API, making the process unexpectedly straightforward and human-centered.

Billions of people communicate with each other using words, while billions of computer programs communicate with each other through API. 10 million of the 23 million developers deal with API on a daily basis (according to techcrunch.com). The API market is expanding at a rate of 33% per year (according to marketandmarkets.com).

There is, however, one problem with API – the documentation. There is no easy way to maintain up to date API documentation at all times. As a result, API documentation quickly becomes outdated. This slows down development, increases the amount of errors, and eventually leads to system architectural degradation. Also, development cost increases by 50% or more.

If there was a simple tool that could supply all companies with 100% up-to-date API documentation, it would change the world of API management. The JSight team does exactly that.