Skip to main content

16 posts tagged with "apidoc"

View All Tags

· One min read
Konstantin Malyshev

This is an image

Today, we are releasing JSight CLI 1.0.0. It helps you to work with JSight API language in a user console. The current release has the following features:

  • Parsing of JSight API files.
  • Checking JSight API syntax (with detailed messages in case of errors).
  • Generating one-file HTML API doc (example).

More details about the product: JSight CLI.

The official release page may be found here: JSight CLI 1.0.0 Release Notes.

· One min read
Konstantin Malyshev

This is an image

Today, we are releasing JSight VS Code Extension 1.0.0. It helps you edit the JSight API specification in your favourite IDE.

VS Code Marketplace link: https://marketplace.visualstudio.com/items?itemName=jsight.jsight.

More details about the product: JSight VS Code Extension.

The official release page may be found here: JSight VS Code Extension 1.0.0 Release Notes.

· One min read
Konstantin Malyshev

This is an image

Today we are releasing JSight Java Validator 1.0.0.

This is a library, which validates all your API requests and responses against your API specification, written with JSight API language.

More details about the product: JSight Validator.

The official release page may be found here: JSight Validator Java Adapter 1.0.0 Release Notes.

· One min read
Konstantin Malyshev

This is an image

Today, we are releasing a new version of JSight Validator PHP Extension 1.0.1.

This is a PHP extension, which validates all your API requests and responses against your API specification, written with JSight API language.

More details about the product: JSight Validator.

The official release page may be found here: JSight Validator PHP Extension 1.0.1 Release Notes.

· 2 min read
Konstantin Malyshev

This is an image

Today, we are releasing a new product: JSight Validator.

This is a library that is designed to validate all incoming and outgoing API messages for compliance with the API specification written in the JSight API language.

It works as follows:

  1. Describe your API in JSight API language and store the resulting API specification in the Git repository of your service.
  2. Integrate JSight Validator into your service code (see manual).

Now all API calls will be validated by the JSight Validator against the API specification! This will provide you with the following benefits:

  • You can always be certain that the implementation of the API is 100% compliant with the specification.
  • You can trust the API specification as it accurately reflects the real API.
  • You don't have to write the validation code of input messages.
  • You don't have to write automated tests to check how the API responds to faulty messages.

For example, in PHP, HTTP request validation might look like this:

$error = jsight_validate_http_request(`my-api-spec.jst`, $method, $uri, $headers, $body);

if( $error ) return jsight_serialize_error('json', $error);

More details about the product: JSight Validator.

· One min read
Konstantin Malyshev

This is an image

We are very excited to announce the release of a new version of JSight Online Editor 5.0.

The official release page is here.

From now on, JSight supports the JSON-RPC 2.0 protocol. Now you can design and document your JSON-RPC APIs with the same ease as general REST APIs.

This is an image

In addition, we fixed a few minor bugs and improved the usability.

You can read more about working with the JSON-RPC protocol here.

· One min read
Konstantin Malyshev

This is an image

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:

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

· 4 min read
Konstantin Malyshev

This is an image

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.

This is an image

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 is an image

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.

· 3 min read
Konstantin Malyshev

This is an image

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.

· 2 min read
Konstantin Malyshev

This is an image

We are happy to announce the release of a new version of JSight Online Editor 4.0..

The official release page is here.

Main feature of the release: You can now share API documentation via a unique link. All you need to do is click on the “Share” button and copy the link.

This is an image

We also thought about versioning the API documentation. It can be done like this:

  1. Open the API documentation via a unique link, for example, https://editor.jsight.io/r/NQBd0BA/1.
  2. Make changes to the API.
  3. Click on the “Share” button and select the option “Update API”.
  4. Your changes are saved with a new link which has a new version number. The new link completely matches the first link, except for the last digit - the version number, which is increased by one https://editor.jsight.io/r/NQBd0BA/2.

This is an image

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 editor's 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).

Another major update in release 4.0 is improved JSight syntax highlighting. Now the editor accurately highlights all the syntax features of the JSight API language.