Skip to main content

2 posts tagged with "apidesign"

View All Tags

· 2 min read
Constantine Malyshev

This is an image

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, the link to the following version would be (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.

· 3 min read
Maxim Reznitskiy

This is an image

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.