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 plan to release a new version of JSight Online Editor by the end of May 2022. Among other minor improvements, there will be two new important features:

1. Smart syntax highlighting, which will allow you to write code in JSight even faster.
2. Sharing API documentation using a link.

Sharing documents via a link will provide our users with three fantastic benefits:

1. Quickly share and discuss an API description with a colleague. You simply need to follow three steps: describe the API, copy the URL, and send the link to a colleague in a chat.
2. Store API documentation in the editor's cloud. Do not forget to save a permanent link to the document in someplace safe.
3. View the entire history of document modifications. The unique version number in the link itself updates whenever the API documentation changes. For example, if the URL to the first version of the API was https://editor.jsight.io/r/pPeJazR/1, the link to the following version would be https://editor.jsight.io/r/pPeJazR/2 (only the last digit changes). So you can always revert to any previous version of the API by simply decreasing the version number in the link.

Thank you for your attention! Along with you, we are also looking forward to the release and your feedback on the new features.

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.

Many of you have requested that API documentation be shared in the JSight Online Editor via a unique URL. That was already in our plans, but considering your request, we decided to address this task earlier. The backend is complete, as well as the requirements specification for the frontend. Right now, we are creating its design. We plan to complete this feature by the end of April 2022.

We considered various UI options, and finally we liked the sharing option made by the guys at https://regex101.com/ (a service for working with regex).

The advantages of this solution:

1. All URLs are permanent. The contents of a unique link never change. This saves us from having to deal with a lot of complexity in the user interface.
2. If you need to change the code in the URL, you can simply create a new version of that URL. For example, you received a link https://editor.jsight.io/r/pPeJazR/1. Once you make edits into the code and save the new version, the new URL turns into https://editor.jsight.io/r/pPeJazR/2 (note that the version number at the end of the link is changed). The following version will include the number 3: https://editor.jsight.io/r/pPeJazR/3 , and so on.

This method is very convenient. Just by looking at the URL, you will understand the version number of your API, and you can always check what was in previous versions just by decrementing the URL version number.

Enjoy JSight Online Editor and share your ideas with us. Your feedback is important to us!

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.

Greetings everyone. Finally, we are pleased to announce the release of our first tool in the JSight ecosystem line: JSight Online Editor.

You can describe your REST API using our new JSight language in JSight Online Editor and get beautiful generated documentation directly in the browser.

Assess the simplicity and power of the JSight language, as well as the convenience of JSight Online Editor right now, without leaving the browser!

Training materials that may be useful to you:

• JSight Language Quick Tutorial
• JSight language specifications: JSight API and JSight Schema.

We intend to release updates to the JSight Online Editor every two weeks starting today. We are planning to include the following features in the next release on February 22:

1. Add a MACRO directive to the language, which will allow you to create macros and reuse code in a flexible manner.
2. Export API documentation to HTML format.
3. Improve JSight syntax highlighting.
4. Make the Rules sidebar on the right more usable.
5. Make other minor improvements.

We have already planned to publish the entire JSight Online Editor code on GitHub this month.

Dear users, your feedback is extremely important to us! Because the goal of our project is to create the most convenient tools especially for you, and no one else.

If

• you don't understand something,
• you found an error,
• are you missing some functionality,
• you come up with a great idea,
• you want to become a part of our team,

then please write to us, we will be very happy:

Email: support@jsight.io
Telegram: @jsight_support

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!