7 posts tagged with "api"

We are pleased to announce that we have released the API sharing function in cloud with a unique link as part of JSight Online Editor release 4.0. This feature is a great addition to the ability to export documentation in a single HTML file. You may now choose whether to download the documentation as HTML or store it in the cloud using a unique URL.

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

1. Quickly share and discuss an API description with a colleague.
2. Store API documentation in the JSight cloud.
3. View the entire history of document modifications. (You can always revert to any previous version of the API by simply decreasing the version number in the link. You can also easily find the most recent API version (more on that below).

Furthermore, there is no need to register anywhere to share via the link, and it is absolutely free.

How to use sharing effectively? There are a great many options, for example:

1. You can quickly design an API on the fly in a team, exchanging links with drafts with each other.
2. You can save all references to all your APIs in Confluence and always have access to the most recent versions of the documentation.
3. You can send a link to the client so that they always have access to the latest version of the API.

See how it works by following the unique API example link: https://editor.jsight.io/r/g6X2ajV/3

Sharing API instructions​

How to share documentation for the new API​

Sharing is done as follows:

1. Describe your API.
2. Press the “Share” button (top right).
3. In the window that appears, copy the unique link to this API.

You can now share this link with anyone, and be sure that the content of the link will never change.

How to update a previously shared API​

If you want to change the content of the link, then you need to create a new version of the API. It is done as follows:

1. Open an existing API link.
2. Make changes to the API description.
3. Press the “Share” button (top right).
4. Select “Update API” (under the “Share” button).
5. In the window that opens, copy the new permanent link. The only difference between the new and original links is the last digit, which represents the serial number of the API version. For example, if your API was saved with the link https://editor.jsight.io/r/qjxZ46a/1, then when you update this API, the new link will be https://editor.jsight.io/r/aL9pnjZ/2 (the last digit has changed from 1 to 2 – this is the version number).

This way you can create as many versions of your API as you want, and each will have its own unique link.

How to check the latest API version​

If you don’t know which API version is the most recent, then you can open the link in your browser without specifying the version, that is, without the last digit. For example, instead of the link https://editor.jsight.io/r/qjxZ46a/2, open the link https://editor.jsight.io/r/qjxZ46a/ (I deleted the number 2 at the end), and the system will automatically redirect you to the latest saved version of your API.

P.S. We are currently working on creating convenient social snippets. This will allow you to immediately see the title and other important parameters of the sent API in the chat when sending a unique link.

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!

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.

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.