10 posts tagged with "JSightLanguage"

We have published the JSight Online Editor code on GitHub under the Apache 2.0 license. Our project was initially intended to be open-source, and we are already a step away from it. Along with the JSight Online Editor code, we also published several libraries and, most importantly, JSight language specifications.

If you’re a developer and willing to spend some time on JSight, welcome to our open-source team! Write to us here:

• Email: support@jsight.io
• Telegram: @jsight_support

Also, if you enjoy JSight, star us on GitHub, this is very important for us.

There is no more difficult choice than choosing between two equally good options.

We had to make hundreds of such decisions when developing the JSight language. Making a decision entails more than just choosing between two alternatives. It's not so much about the decision, as about the criteria for making decisions. Firstly, you need to understand why the existing decision criteria do not help you choose the right option. Then, you need to modify these criteria. After that, making the decision itself is no longer difficult.

Today we are going to share about one of such cases.

In most data structures, certain fields are mandatory while others are optional. This needs to be somehow marked in the data schema. In our case, there were two possible solutions: add either a rule required or a rule optional to the language:

{
  "id": 123     // {required: true}
  "name": "Tom" // {required: false}
}

Or this way:

{
  "id": 123     // {optional: false}
  "name": "Tom" // {optional: true}
}

The second question following the first is what should be the default value: required: true or required: false? And accordingly in the case of optional, optional: true or optional: false? When I see a property in an example of valid data, it intuitively seems to me that this property “should be”, unless otherwise stated. This means that by default, required: true or optional: false is correct. Then we have the following options:

{
  "id": 123
  "name": "Tom" // {required: false}
}

Or this way:

{
  "id": 123
  "name": "Tom" // {optional: true}
}

Which option do you prefer? Please write in the comments to this post, we are interested!

After comparing both options, we decided to rely on this criteria: which at first glance is perceived as faster and more in line with intuition?

The brain is used to interpret information in the simplest way. When we see the word required..., our initial assumption is that this property is required, since that is what the word required means. Then, reading the rule till the end required: false, we experience cognitive dissonance. We initially assumed that the field is required, but it turns out that required: false.

There is no cognitive dissonance in the case of optional: true. We see the word optional... and we automatically assume that this property is optional. Then we read the rule till the end optional: true and find confirmation of our initial thought.

So, considering how quickly the schema is intuitively perceived, optional fits better than required. However, another strong criteria works in favor of required: this word is more familiar to us, it is used, for example, in JSON-Schema, OpenAPI, RAML.

What is more important: convenience or habit? After long debates, we concluded that since we were creating a completely new language, convenience is more important, therefore we went with optional. Time will tell whether we were right or not.

Programmers are already lazy enough. Typing extra text is not their thing. Less code with more benefits!

Programmers are aesthetes. The code must be lovely. Beautiful code is inexplicable and must be experienced.

We are programmers. And have done everything we could to make the JSight language concise and beautiful. And finally, it looks like we’ve got it!

For example, see what a simple API on JSight looks like:

JSIGHT 0.3

GET /cats/{id}
  200
    {
      "id"   : 123,   // {min: 0}
      "name" : "Tom"
    }

Any programmer, without requiring any explanation, will immediately and unmistakably understand what this API is about. Nothing superfluous! Every word, every letter has an important and precise sense.

Compare the same API on OpenAPI (Swagger):

openapi: 3.0.3
info:
  title: ""
  version: ""
paths:
  /cats/{id}:
    get:
      parameters:
      - name: id
        in: path
        required: true
        schema: {}
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                type: object
                required: [id, name]
                properties:
                  id:
                    type: integer
                    minimum: 0
                    example: 123
                  name:
                    type: string
                    example: "Tom"

Doesn't this code seem redundant, to put it mildly?

We’re not criticizing OpenAPI. We’ve previously used it a lot and truly love it. But the world is moving forward and outdated technologies have to give way to new ones. It's time to move on to JSight, which is both concise and beautiful.

You can try out the JSight language right now: editor.jsight.io!

Learn more about JSight in a quick tutorial and in the official specification.

We have a good tradition of matching upcoming releases in line with the wishes of our clients. One more case: at the request of our clients, we took up the task of developing support for JSON-RPC 2.0 standard.

Let’s reveal a little mystery. We intended the JSight language to be designed not only for REST API documentation, but also for support of other popular data exchange methods (JSON-RPC, gRPC, Kafka, RabbitMQ, WebSocket, etc.).

We are beginning with JSON-RPC 2.0 since:

1. JSON-RPC 2.0 is a very popular standard that is frequently chosen by developers when RPC architecture is preferable to REST.
2. It is a very simple standard that could quickly be supported by our team.

At the moment, we have prepared amendments to the JSight language specification and designed the user interface. In the next few days, we will begin development.

Code example describing JSON-RPC methods:

JSIGHT 0.3

URL /api/rpc
  Protocol json-rpc-2.0

  Method createCat // Create a cat.
    Params
      {
        "cat": @cat
      }
    Result
      {
        "id": 1 // Cat’s id.
      }

  Method getCat // // Get a cat by its id.
    Params
      {
        "id": 1 // Cat’s id.
      }
    Result
      @cat

TYPE @cat
{
  "id": 1,
  "name": "Tom"
}

The code is really simple and clear, isn’t it?

Design example:

We plan to release JSON-RPC support by the end of June 2022.

Enjoy JSight Online Editor, follow the news, and share your ideas to support@jsight.io!

Hi everybody! We have a new release of JSight Online Editor 3.0! The official release page may be found here: JSight Online Editor 3.0 Release Notes.

There are two cool features in this version:

Firstly, “Preview” and “Export” buttons are added. By using these buttons, you can see the final API documentation design and, if you like it, download it in HTML format.

Secondly, we have added macros support into the JSight language. And it's really very cool! JSight now looks like a true programming language (programmers will understand us). With the directive MACRO, you may now declare a macro, and with the directive PASTE, you may paste this macro anywhere in your API an unlimited number of times. Macros are useful, for instance, for quick attachment of standard responses to each resource in case of an error. As an example:

GET /cats

  200 [@cat]
  PASTE @commonErrors

GET /dogs

  200 [@dog]
  PASTE @commonErrors

MACRO @commonErrors
(
  400 any
  401 any
  405 any
  500 any
)

You can read more about the directives MACRO and PASTE in the JSight language specification:

• Directive MACRO,
• Directive PASTE,
• and also in the Quick Tutorial.

We have also improved the UX in some places and fixed a few minor bugs.

We plan to release the next version of JSight Online Editor 4.0 by the end of May. The main innovation of this version will be the “Share” button. With this button, you will be able to save documentation in the cloud and share it with colleagues just by sending them a unique link to the document.

We also hope to add JSON-RPC support to the JSight language in the near future.

We’re starting a series of posts about the key features of the JSight language, which set it apart from all other API description languages and make describing API easier and faster.

Today, we’ll discuss the main feature, which we refer to as “Example as a schema”.

Any API description language describes data schemas in one way or another. For example, WSDL uses XSD to describe data, Blueprint API uses JSON Schema, and OpenAPI uses Schema Object.

The JSight API language uses the JSight Schema language to describe data. The JSight Schema approach, on the other hand, is fundamentally different from any other method of describing schemas. Now we'll tell you about this difference.

In 2020, Swagger interviewed over 3,000 IT specialists, asking them to name the top 5 most important things they seek in API documentation. What do you think the most popular ones were among the respondents? 70% of the respondents answered that they need EXAMPLES.

Unlike all other languages, the JSight Schema language primarily focuses on sample data. And this is completely justified. Programmers love examples! After all, most of the time, just looking at the example is enough to figure out what the data structure is.

In the JSight Schema language, the data example is already a data schema. For example, here is the simplest schema for you:

{
    "id": 123,
    "name": "Tom"
}

It is obvious from this schema that the data must be an object with an “id” property of type integer and a “name” property of type string. And if you need to add additional requirements to the schema that are not obvious from the sample data, then these requirements can be placed in a small JSON in the comments to the property:

{
    "id": 123, // {min: 1}
    "name": "Tom"
}

In the given diagram, it is added that the value of the “id" property must be greater than or equal to one.

For comparison, a similar schema in the OpenAPI language will look like this:

 type: object
 required: [id, name]
   properties:
     id:
       type: integer
       minimum: 1
       example: 123
     name:
       type: string
       example: "Tom"

Do you notice any differences?

On JSight, the schema is simpler, shorter and more appealing to the eye.

You can learn more about JSight Schema in our tutorial and in language specification.

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!

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!

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!