REST API Automation Documentation generation

This is a creation in Article, where the information may have evolved or changed.

A REST API Automation document generation capability

Currently, as a standard connection between most mobile apps and the cloud service backend, the REST API has been recognized and widely used by most developers. In recent years, in the emerging API economic model has emerged, many vendors have their back-office capabilities as a rest API open to the wider use of third-party developers.

However, managing the rest API is not an easy task. Due to the lack of valid interface data schema constraints, as well as the arrangement of resource endpoint when designing the rest API, and the way in which HTTP requests are sent, after the rest API is developed, in most cases API developers still need to manually write API documentation , allowing the user to follow the documentation's instructions for access. and rewriting the document when the API changes, the process is laborious and error-prone. For example, a REST API document must specify the following basic information at a minimum:

• Name of the API

• URL resource path where API is located

• HTTP request method (GET, POST, put, etc.)

• How the API submits data (query parameters, form submissions, JSON submissions, etc.)

• Calling API returns the format of the data

In the rest API information provided above, the JSON data returned from the API can, in most cases, only illustrate the structure of the data in the "example" way, rather than accurately expressing the exact meaning and type definition of each field in the JSON data. This is because the rest API lacks a schema definition for JSON data, and this "example" is undoubtedly a very helpless and silly approach. When we are in the development of the interface with other vendors, often the other side of the document is not clear, the need to manually confirm the communication, even if we have the correct understanding of a data parameter or return results, this is a very time-consuming work.

When the business changes, any of the above information about the rest API changes, such as adding a new field to the return result, the developer has to re-write the document again and then resend the document to the API user changes, which can be painful if repeated iterations occur. While there are some API design and documentation tools, such as the Swagger UI, which help developers to write documents more easily, they do not eliminate the complexity inherent in the rest API.

The API management solution provided by the long-length technology is a perfect solution to the rest API documentation issues described above. The core technology of the CDIF technology is the API management framework called the. CDIF is the world's first JSON-based SOA solution. The rest API managed by Cdif can automatically generate their API documentation, saving developers time and effort in managing API documentation. The frame design of the cdif can be represented by:

In Cdif, the rest API is packaged uniformly into a variety of driver packages, each of which is a standard node. js NPM package. Each driver package can contain access code for any number of rest APIs. In the implementation of the driver package, each REST API must provide a unified, common API model for the client, according to the specifications provided by CDIF. This API model is a JSON document that contains all the information about how to access the API. Compared to the rest API documentation above, this API model contains only the following information:

• Name of the API

• JSON schema definition for API input parameters and return results

Other information about the rest API is considered an internal implementation of the API driver package and does not need to be exposed to external API users.

API models based on the CDIF definition specification have API descriptions that are equivalent to XML-based WSDL. Based on this, the API management tools associated with CDIF can automatically parse this JSON document and automatically generate documents from its managed Rest API. A clear and easy-to-read SMS API document that is automatically generated on the API market for the long-length technology:

The above details can refer to the long-length technology API Market

In the above API documentation, the type, description, constraints, API error messages for each field in the request and return data are automatically generated from the JSON schema file provided by the user in the API package, and the exact description of the API and data 100% is true. Developers only need to write the API model according to the specification definition provided by CDIF, upload a NPM package that includes only dozens of lines of API access code to the API management platform of the long-range technology. When the API parameters or the return results need to be updated, users only need to update the content of the JSON schema file in the NPM package, re-upload can automatically obtain new API documentation.

When accessing this CDIF managed Rest API, the user simply needs to access the CDIF for a fixed URL address provided by the rest API that it manages, and it only requires the client to support the HTTP POST method to submit the API request data. All submitted data, in accordance with the JSON schema constraints, are all placed in the HTTP request and the returned JSON body. This design is the classic WSDL + SOAP implementation, very simple to use and good compatibility. At the same time, with the powerful performance of JSON schema, CDIF can support arbitrary complexity of API interface data. Most popular development languages now support the submission of API requests in the form of post JSON data, so the API provider provided by CDIF is already supported by the broadest client development environment. In the future, we will add the client API access code auto-generation capability in various languages, and the API users can simply copy and paste the code to access, further simplifying the development and use of the API to facilitate the process.

In addition, when the internal implementation of the API package needs to change, the user only needs to modify the API package code, re-upload and can deploy a new version with a single click. CDIF supports hot swapping of API package code, and does not even affect the process of invoking an older version of the API that is occurring on the line. This greatly facilitates and simplifies the developer's API development experience.

Furthermore, developers can automatically have API test pages for API developers and API users to easily debug API usability after uploading the API package. Next time we will introduce this feature we provide, please pay attention to.

The

Cdif framework and CDIF-based API management solutions are currently developed by Shanghai Software Technology Co., Ltd. and are open to use by all API developers, welcome to our website apemesh.com register and apply for a trial of our API management solution.