When performing our duties at work, many of us face the need to look into any directory that will give us an answer to our question. If you are an ERP / CRM user, you contact IT support immediately in case of any questions arise. If you are a lawyer, you need a corresponding code on which you have a question. If you develop Web applications for your business or your customers, you will simply need development standards and documentation for your API. Each sphere has its own documentation, from which people derive the information they need to carry out their work.
It seems everything is so simple. However, in the IT (Information technology), everything changes very intensively. Relations of programs, applications, etc. through API (Application Programming Interface) are also constantly changing. Many programmers face the need to look through the standards of their programming language, an API for their current task, the ways to formalize it all for easier and more comfortable work through the documentation in the future.
API Documentation
API documentation is technical documentation containing instructions on how to effectively use a software API, hardware SCPI or web API.
For actively developing products, API documentation support plays an important role, but one should not forget about the relevance of these data.
One of the options for resolving API documentation task is hiring an employee (employees) to create API documentation. He (they) will distribute this documentation in the form of files or publish it on a site. This approach is quite working, but has a number of significant shortcomings such as human factor and rapid obsolescence of the documentation. A person can forget something, write wrong, etc. Once the code has changed, the documentation becomes obsolete. API-interfaces developers come across irrelevant and erroneous documentation very often. The search for "truth" in such cases increases labor costs and that ultimately affects product value.
Thus, API documentation is meant for not only formalizing the necessary information in a document, but also maintaining its relevance.
Let us suppose API documenting has been brought to actuality, and now we always have unmistakable information in our access. However, unfortunately, when there is actual documentation, the difficulties do not end. The resulting API can be so complex and inconvenient that working with it can become a nightmare. After all, people will work with it first, and then the program. Obviously, we need a certain API development standard, so that developers, even after quick review, understand how to interact with it correctly. In addition, API standards availability allows automatic code generation use, which significantly increases development speed.
API Documentation Task Solving
Before proceeding to solving the tasks that arise, you need to know the existing Web services implementation protocols, their work, their features, and find out more about different API interfaces standardization tools.
Existing API Web Services
Web interfaces or Web APIs are actively used in Web development. As Internet systems develop, some web APIs become obsolete, such as SOAP (Simple Object Access Protocol), while others are in high demand, such as REST (Representational State Transfer). You can also find the "dark horse" GraphQL, launched by Facebook in 2015. The diagrams of API Web services are shown below.
Figure 1. REST Web service
Figure 2. GraphQL Web service
Possible Solutions for REST Architecture
It is not easy to establish consistent communication between all kinds of clients and a server application. This problem is partly solved by the basic provisions of REST architecture (or any other architecture you choose); however, server interface (API) description is indispensable. In other words, client applications developers must somehow understand how they can interact with a server application, what impact this will have and what they will get as a result.
Currently, one of the most popular API description methods is Swagger specification. Swagger is not only a specification, but also an entire ecosystem for solving a variety of API documentation tasks.
Specifications list for RESTful API documentation:
Autogeneration is Our Everything
There is a solution of the above mentioned difficulties in API documenting – autodocumentation generation, i.e. automatic documentation alteration after changing an application code to reflect these changes. It eliminates both the human factor and the problem of irrelevance. Of course, this method requires certain expenses at the initial stage. It is necessary to configure API documentation generation system, and also to develop a set of rules of writing a code and adhere to it.
TQM systems Case: Solving REST API Documentation Task
When developing our own Web services and facing similar problems in API documentation, our developers found an interesting solution described below. So, how did we carry out REST API documenting?
Why REST API?
When developing Web applications, we use REST approach to implement the server side of an application. This approach allows you to easily add new kinds of client applications able to work with application`s main business logic. For example, at the initial stage, you can use only browser as a platform for user interface implementation, and then add applications for smartphones or desktop computers running various operating systems. Since the concept of IoT (Internet of Things) is gaining momentum, not only a person can become a client of our application, but also any device. The probability of having to rewrite everything because users began to prefer one mobile platform to another has been significantly reduced. Now it is enough to implement a client for a new platform. There is no need to spend resources on processing the main functionality, which has already been tested and works well.
REST API Documentation Method
When developing our SaaS Solutions product, we implemented a RESTful Web service and an application for operating in a browser using .Net Framework + Asp Net Web Api + Angular.js technology bundle. To generate the documentation, we used Swashbuckle library, which implements documentation generation on Swagger specification for .Net solutions.
Ready API Documentation Example
As a result, we have this Web page describing API.
Figure 3. Example of API documentation generated by Swashbuckle library.
It is not just a page describing the API, it also gives an opportunity to test the API without using third-party tools.
Figure 4. Web API documentation with API output
The above-mentioned Web API documentation demonstrates that even at the design stage it is already suitable for internal use. Its availability greatly simplified the interaction between server and client applications development teams. After adding descriptions of work methods and return values formats, it can be applied for external use.
Copying of this content is allowed only with reference to the source and indication of the author of TQM systems material.
made by Elena Teplitskaya, editor of TQM systems
Web Apps developing
Automation of business
IT Expertise
IT integration
If you would like to get new blog posts, articles, news and white papers by email - submit!
Our IT-company was established at the 2008 with young talanted people.
Our mission is to simplify data management.
Copyright © 2008-2024 TQMsystems. All Rights Reserved. Privacy Policy | Terms of Service
