CN114625341A - REST API design quality evaluation method - Google Patents

Abstract

The invention discloses a REST API design quality evaluation method, which comprises the following steps: 1) establishing a RESTful standard system; 2) acquiring or constructing an API description document data set, and classifying the documents according to API category information to obtain a plurality of field data sets; 3) analyzing each API description document, extracting the version number of the API description document, and then constructing a corresponding syntax tree for the API description document according to the version number; 4) detecting whether component information of each syntax tree can be realized according to the RESTful specification system, and determining an evaluation reference value of REST API; 5) determining an evaluation value P of an REST API to be detected aiming at the REST API to be detected; field j combined with REST API to be detected and corresponding field evaluation reference value P_jAnd evaluating to obtain the RESTful degree of the REST API to be detected.

Description

REST API design quality evaluation method

Technical Field

The invention relates to a REST API design quality evaluation method, combines the current situation of REST API comprehensive development and field characteristics, and belongs to the technical field of computer software.

Background

Web services play an important role in the development of applications, and Service Oriented Architectures (SOAs), particularly microservice (microservice) architectures, are common practices when building applications. More and more applications are developed using a service-oriented architecture, and REST (Representational State Transfer) is the most popular web services architecture style.

REST is based on the HTTP protocol, is suitable for a network service that provides services through the HTTP protocol, presents resources in the form of network entities, and performs request operations through the HTTP standard method, and has become a standard way for most service providers to provide network services.

However, REST is only an architectural style and does not provide a standard specification. This means that developers need to make certain decisions on their own when opening services, which can lead to different API designs, even poor design decisions, and uneven quality of network service interfaces on the market. Some non-standard designs, such as non-standard interface naming, incorrect use of the HTTP method, unreasonable resource granularity design, etc., result in unreadable API machines, human-unfriendly, bury its use, academic and economic values, and even may cause overflow of service logic of the service to cause potential safety hazards. Therefore, API design quality analysis and RESTful degree evaluation are currently needed research work; research on the REST API evaluation method is of great significance to standardizing the network service market now and in the future.

The current REST API evaluation work is focused on by academia, forming some relevant achievements. The focus of some current research work is mainly on the research and detection of design patterns (reverse patterns) based on the best practices of REST APIs, forming a specification system, and then evaluating the REST APIs. Research work (Palma, Francis, Johann Dubois, Naouel Moha, and

gue h neuc, "Detection of REST patterns and anti signatures, a heiristics-based approach," In International Conference on Service-Oriented Computing, pp.230-244 Springer, Berlin, Heidelberg,2014.), defines eight REST anti-patterns and five design patterns, proposes a method for detecting (anti) patterns In a RESTful system based on a heuristic SODA-R (Service-Oriented REST Pattern Detection), and detects In 12 widely used REST APIs (including BestBuy, Facebook, and DropBox), which indicates that SODA-R can be detected by SODA-RA precision detection REST (inverse) mode is performed. Research work (Neumann, Andy, Nuno larnjeiro, and join bernardino, "An analysis of public REST web service APIs," IEEE Transactions on Services Computing (2018)), analyzed the key technical characteristics of 500 APIs, the degree of compliance with REST architecture principles (e.g., resource addressability) and with best practices (e.g., API version control), observed some trends (e.g., extensive JSON support, software-generated documentation), with only 0.8% of Services strictly adhering to all REST principles. However, the current RESTful evaluation work has a general overview of all APIs, and does not consider the characteristics of APIs in different fields and make targeted evaluation.

Disclosure of Invention

The invention provides a REST API design quality evaluation method aiming at REST API and considering different performance characteristics of API in different fields, researches find the current comprehensive development situation and field characteristics of the current REST API, analyzes and evaluates user API in a targeted manner, provides guidance suggestion for REST API design, and aims to standardize the network service market.

The purpose of the invention is realized by the following technical scheme.

The REST API design quality analysis method provided by the invention comprises the following steps:

1) establishing a RESTful (REST design style-conforming) specification system, designing REST API from different dimensions, including three dimensions of resource design, HTTP interaction design and non-functional design of RESTful API, establishing the specification system under each dimension, and determining a measurement rule of each specification: whether {0, 1} or degree of achievement [0,1] is achieved;

2) the OAS (openapi specification) specification (including OAS 2.0 and OAS 3.0) is a REST API specification document specification widely used at present, constructs an API specification document data set conforming to the specification, and constructs a field data set according to API category information, specifically including the steps of:

2.1) API, guru (site of OAS document maintaining REST API) records API provided by platform or service provider in each field, wherein the API includes one or more API description documents and description documents of different versions of the same API, firstly, acquiring all API description document data set;

2.2) cleaning the data set, keeping the description document of the latest version for each API, and removing the description document which does not contain path information in the data set;

2.3) finally establishing a domain data set, extracting the category information of the API, and searching the category of the API which does not contain the category information in API. guru in a programable Web (a site for maintaining REST API); and classifying the data sets according to the category information, sampling the API description document of each category by using an open card method, voting the categories of the sample API, and combining 64 categories into 16 fields to construct 16 field data sets.

3) Analyzing REST API description documents in the API description document data set, wherein the REST API description documents comprise a Yaml format and a Json format, extracting an OAS version number to be followed, if the version number is 2, analyzing the documents to construct a swagger syntax tree (swagger-models-2), and if the version number is 3, analyzing to construct an openAPI syntax tree (swagger-models-3); the purpose of constructing the syntax tree is to perform format detection on input, check whether the input is an API (application program interface) specification document which meets the specification or not, and successfully construct the syntax tree so as to facilitate subsequent operation to obtain relevant component information;

4) acquiring syntax tree components, and detecting whether the corresponding specification (the specification system constructed in the step 1) is realized; and calculating the overall standard realization condition of the REST API and the standard realization conditions of the APIs in different fields as reference values of the REST API evaluation, wherein the specific contents of the step comprise:

4.1) extracting path (Paths) information in the syntax tree, and performing standard verification on path naming, wherein the specific verification comprises the following aspects:

a) no verb appears in the naming: constructing a verb list to be detected, verifying whether a verb appears in resource naming by using a heuristic method, and calculating the realization degree p of the API to the specification_noCRUDThe calculation method is shown in the following formula, n_noCRUDRepresenting the number of Paths (Paths) without verbs appearing in the API, and N representing the total number of Paths of the API;

the specific detection method comprises the following steps:

a1) firstly, segmenting a path, taking each level (attribute removal part) as a sentence, and distinguishing the words in url in three ways: using a hump-type structure, using separators (including spaces) and having no obvious distinction, therefore using a word segmentation algorithm based on dynamic specifications, i.e. seeking a word segmentation mode which maximizes the probability product of each word to obtain a word set;

a2) performing part-of-speech tagging on the word set by using NLTK to obtain a verb set, screening verbs according to whether semantics can be mapped to an HTTP standard method, removing verbs which have no practical meaning and are difficult to describe by the HTTP standard method, realizing the rest verbs by the HTTP standard method, constructing the remaining verbs into a violation word set without appearing in path naming, and arranging the violation word set in a descending order according to the occurrence times to increase the retrieval speed;

a3) constructing a misunderstanding word set (high-frequency misunderstanding word set) for each violation verb, namely a noun containing the violation verb, increasing the detection accuracy, such as a path "/address", wherein the path can be falsely detected as a verb to appear due to the fact that the noun "address" contains the violation verb "add";

a4) detecting the standard, and if a violation verb appears in one path and no mishaped word set appears, namely violating the standard: verbs appear.

b) Path naming using lowercase: converting Paths (Paths) into lowercase by using lowercase (), comparing the path with the original path to verify whether the path uses lowercase letters, and calculating the realization degree p of the API to the specification_lowercase，n_lowercaseRepresenting the number of Paths named by lowercase letters in the API, and N representing the total number of Paths of the API;

c) no "api" wording appears in the nomenclatureNo underlining "_": using index () method to detect whether "_" and "api" appear in the path, both are information that should not appear in the RESTAPI specification, and calculate the degree of implementation p for these two specifications, respectively_noUnderlineAnd p is_noapi，n_noUnderlineIndicates the number of paths in the API that are not underlined, n_noapiRepresenting the number of Paths in the API without the appearance of the word "API", and N representing the total number of Paths of the API;

d) no information representing the version appears in the naming: the path is detected as a regular pattern, using the pattern "v (ers? [0-9.]+ "to detect if version information is present in the path and calculate the degree of implementation p for the specification_noVersion，n_noVersionRepresenting the number of Paths without version information in the API, N representing the total number of Paths of the API, and suggesting that the version information is identified in a header file;

e) the resource manifestation, i.e. format suffix, does not appear in the nomenclature: and detecting whether the resource expression form appears in the path or not by comparing with the resource expression form list (file format suffix), wherein the REST API requires url to only identify the resource without embodying the concrete expression form, and calculates the realization degree p of the specification_noSuffix，n_noSuffixRepresenting the number of Paths without resource format suffixes in the API, and N representing the total number of Paths of the API;

f) the path hierarchy is divided using "/", and the tail slash does not appear in the path: using index () method to detect if "/" appears in path naming, if it appears, further detecting if its position is inThe last bit, and calculates the implementation case p of the specification "no tail slash occurrence_noEndSlash(ii) a And simultaneously calculating the hierarchy number h of each path according to the number of occurrences of '/'_ijThe hierarchical level of the jth path of the ith API is represented, the API has m paths, and the average path hierarchical level of each API is calculated, and the calculation formula is as follows:

calculating the average path level Avg (all/domain) of all data and each field data set, wherein the data set comprises n APIs (application programming interfaces), the ith API comprises p_iThe layer number of the ith path of the ith API is h_ij：

Calculating the maximum layer levels Max (all) in all paths, and the maximum value Max (AvgHierarchy) in the average layer levels of all APIs, wherein the calculation formula is as follows:

Max(all)＝max(h_ij)

4.2) extracting attribute (Parameters) information in the syntax tree, wherein the attribute information comprises three levels of attributes: the API attribute use specification is verified according to the global attribute, the path level attribute and the operation level attribute, and the specific verification comprises the following aspects:

a) detecting whether the attributes appearing in the path have corresponding description information;

b) detecting whether functional attributes appear in the query attributes, such as paging, date filtering and the like, and performing preliminary processing on the resource response result to increase the usability of the API; the detection is performed by using an algorithm based on fuzzy matching of keywords, and the keyword list is 'limit, offset, page, range, pagesize, pagestartindex, before, after'.

4.3) calculating average conditions of all API realization degrees aiming at each specification and realization conditions P of APIs in different fields_j(the average value of m APIs belonging to field j for a certain standard implementation case p) is used as an industry standard of the standard to compare and evaluate the RESTful degree of the API.

5) Analyzing the API description document of the target to be detected aiming at a certain REST API to be detected, and comparing the field average implementation condition P obtained in the step 4.3)_jPerforming RESTful evaluation on the tested API, and specifically comprising the following steps:

5.1) carrying out steps 1-4) on the API description document to be tested, detecting the implementation degree of each specification of the API description document, and calculating the p value of each specification;

5.2) combining the field standard reference P obtained in the step 4)_jTo evaluate the target API using the ratio calculation method P/P_jAnd obtaining the RESTful degree of the target API in the field to which the target API belongs, namely a quality evaluation result of the REST API.

The invention has the positive effects that:

by adopting the method, the design quality of the REST API can be analyzed and evaluated in a targeted manner, and guidance suggestions are provided for API design, so that the design of the REST API is more standardized.

Drawings

FIG. 1 is a flow chart of a REST API design quality analysis method.

Detailed Description

The invention is further illustrated below by way of example with reference to the accompanying drawings and APIs in two different fields.

Take Github's API Specification document as an example.

The method comprises the following steps of acquiring an API description document provided by a user, and supporting three modes: and obtaining through a network request according to the url, uploading the file and obtaining the text form. Analysis evaluation of the API is then started, and as shown in FIG. 1, the API description document for Github is first parsed to extract the OAS version number it follows, with the first line "swagger: '2.0' ", indicating that the API specification document conforms to the OAS 2.0 specification. It is constructed as a swagger syntax tree according to the specification.

Then extracting the category information thereof, such as "x-apisgutu-categories: and (4) collaboration ", namely Github belongs to the field of collaboration, and the final analysis result is compared with the API RESTful condition in the field of collaboration.

The analytical evaluation of the API was started next. Extracting components such as paths, parameters, security and the like, counting that the number of resources (paths) is 156, and the average number of resources in the field is 74.8; the number of the path average layer levels is 3.85, which is higher than the industry average value of 2.96, so that the resource is more, and the structure is more complex; on average, each path has 1.56 endpoints, the domain average is 1.4, and it can be seen that GitHub has a higher average operand for the resource than the industry average. For the analysis of the usage attribute, a functional attribute "start-page" is used for paging to enhance the usage level of the API. The security mechanism uses the OAuth2 protocol.

The url of the path is further extracted to verify the API path name: for the verb not appearing in the canonical naming, paths such as "/gist/public"/gist/{ id } ""/gist/{ id }/comments "of the GitHub use resource nouns to name the service, and verbs which manipulate the resources do not appear, the canonical achievement rate is 100%, and 105% of the industry average level (95%) is achieved; the realization rate of the specifications such as the backslash, the version information, the api character and the like which do not appear in the path is 100 percent and is higher than the industry standard; the realization rate of using lower case letters is 84.6%, and a hump segmentation mode is only used in part of attribute naming to reach 134% of an industry standard (63%); the realization rate of the path that the dividing line is used for dividing without underlining reaches 94.2 percent, and is also higher than the industry standard 89 percent. Therefore, the RESTful degree of the Github resource design is integrally superior to the API in the same field.

Extracting operation information in the pages, analyzing the use condition of the HTTP method, wherein several standard HTTP methods for operating resources are used, wherein the GET method for acquiring the resources is used at most and reaches 59.8%. The HTTP method is used correctly, GET acquires resources, DELETE DELETEs resources, PATCH method is used for modifying and updating resources, PUT method is used for following, star marking warehouse is used, and the like.

And finally, displaying the analysis result to a user in a visual mode.

Com, take as an example the description document of the awsmigitationhub service provided under amazonaws.

The API belongs to the cloud class, and various services are provided in the cloud field, so that several HTTP methods are involved; the provided service structure is complex, and the average level number is 6.3; and some services are difficult to map on a standard HTTP method, and the average realization rate of no verb in the path is 91%; to describe these service path names requires segmentation, most APIs in this field still use a humped naming scheme, with path names using lower case letters with an average implementation rate of only 10%.

The API is evaluated against industry standards, which indicate that the document conforms to the OAS3 specification to establish an open API syntax tree, and relevant components of each specification are extracted for detection. The RESTful degree of this API is low: all use POST method to initiate the service request, do not use HTTP method correctly; the paths are not subjected to layering treatment, the average layering level is 1, services are all described in the same layer, a hump type is used for phrase segmentation, and the realization rate of path using lowercase is 0; the traditional network service naming modes of action xxx and target xxx are used for naming paths, and the realization rate (64.7%) of no verb in the paths only reaches 71% of the industry standard. The RESTful degree of the API is low, and the API has a large optimization space.

The REST API is analyzed from different dimensions, and compared with the existing analysis method, the method and the device add information specific to the field, and achieve targeted analysis of the API in different fields.

The above description is only for the purpose of illustrating the preferred embodiments of the present invention and should not be taken as limiting the scope of the present invention, which is intended to cover any modifications, equivalents, improvements, etc. within the spirit and scope of the present invention.

Claims (8)

1. A REST API design quality assessment method comprises the following steps:

1) establishing a RESTful standard system, designing REST API from different dimension standards, establishing the standard system under each dimension, and determining a measurement rule of each standard;

2) acquiring or constructing an API description document data set which accords with REST API description document specifications, and classifying the API description document data in the API description document data set according to API category information to obtain a plurality of field data sets;

3) analyzing each API description document in the API description document dataset, extracting the version number of the API description document, and then constructing a corresponding syntax tree for the API description document according to the version number;

4) acquiring component information of a syntax tree, and detecting whether the component information can be realized according to the RESTful standard system; then, calculating the whole standard realization condition of the REST API and the standard realization conditions of the APIs in different fields according to the realization condition of the component information of each syntax tree, and using the calculation conditions as the evaluation reference value of the REST API;

5) analyzing an API description document of the REST API to be detected and constructing a corresponding syntax tree H for the REST API to be detected, detecting whether component information of the syntax tree H can be realized according to the RESTful standard system, and determining an evaluation value P of the REST API to be detected; combining the field j to which the REST API to be detected belongs and the corresponding field evaluation reference value P obtained in the step 4)_jAnd evaluating the REST API to be detected to obtain the RESTful degree of the REST API to be detected in the field to which the REST API belongs.

2. The method of claim 1, wherein the dimensions comprise three dimensions of resource design, HTTP interaction design, and non-functional design of a RESTful API.

3. The method according to claim 1 or 2, wherein the method of classifying the specification document dataset according to the API classification information is:

21) cleaning the API description document data set, reserving the API description document with the latest version for each API, and clearing the API description document which does not contain the path information;

22) extracting the category information of the API, and for the API without the category information, searching the category of the API in a site for maintaining the REST API; and then classifying the data sets according to the category information, sampling the API description document of each category, and combining sampling results to obtain a plurality of field data sets.

4. The method of claim 1, wherein the reference value for the REST API evaluation is obtained by:

41) extracting path information in the syntax tree, and carrying out standard verification on path naming according to the RESTful standard system;

42) extracting attribute information in the syntax tree, and verifying the API attribute use specification according to the RESTful specification system;

43) for each specification, calculating the average implementation degree of all APIs for the specification according to the verification result of the specification and the field specification reference P of different field APIs for the specification_j。

5. The method of claim 4, wherein the specification that validates path naming comprises:

a) no verb appears in the naming: constructing a verb list to be detected, verifying whether a verb appears in resource naming by using a heuristic method, and utilizing a formula

Computing the degree of implementation p of an API on a specification a)_noCRUD(ii) a Wherein n is_noCRUDRepresenting the number of paths without verbs in the API, and N representing the total number of paths of the API;

b) path naming using lowercase: converting the path information into lower case, comparing with the original path to verify whether the path uses lower case letters, and calculating the path information according to the formula

Computing the degree of implementation p of an API to specification b)_lowercase，n_lowercaseRepresents the number of paths in the API named using lower case letters;

c) the word "api" does not appear in the nomenclature, the underlining "_": detecting whether the _ ' and the ' api ' appear in the path and according to the formula

Separately calculating the degree of implementation p of the API to the specification c)_noUnderline、p_noapi(ii) a Wherein n is_noUnderlineIndicates the number of paths in the API that are not underlined, n_noapiRepresenting the number of paths in the API where the "API" typeface does not appear;

d) no information representing the version appears in the naming: regular pattern detection is carried out on the path, whether version information appears in the path or not is detected, and the path is detected according to a formula

Computing the degree of implementation p of an API on a specification d)_noVersion(ii) a Wherein n is_noVersionRepresenting the number of paths in the API where no version information occurs;

e) the resource manifestation, i.e. format suffix, does not appear in the nomenclature: comparing the resource expression form list, detecting whether the resource expression form appears in the path, and according to the formula

Computing the degree of implementation p of an API on a specification e)_noSuffix(ii) a Wherein n is_noSuffixRepresenting the number of paths in the API where no resource format suffix appears;

f) the path hierarchy is divided using "/", and the tail slash does not appear in the path: detecting whether a '/' appears in the path naming, if so, further detecting whether the position of the path naming is at the end position, and calculating the implementation condition p of the specification of ' no tail slash occurrence_noEndSlash(ii) a And simultaneously calculating the hierarchy number h of each path according to the number of occurrences of '/'_ij，h_ijAnd representing the level number of the jth path of the ith API, and calculating the average level number of the path levels of each API.

6. The method of claim 5, wherein the method of verifying whether a verb is present in the path information comprises:

a1) firstly, segmenting a path to obtain a word set;

a2) performing part-of-speech tagging on the word set to obtain an action word set, screening verbs according to whether semantics can be mapped to an HTTP standard method or not to obtain verbs which should not appear in path naming to obtain an illegal word set;

a3) constructing a misunderstanding word set V for each violation verb V, wherein the misunderstanding word set V comprises a plurality of nouns containing the violation verb V;

a4) and if the verb in the violation word set appears in one path and does not belong to the misunderstanding word set, judging that the verb appears in the path.

7. The method of claim 4, wherein the specification that verifies the API attribute usage specification comprises: detecting whether the attributes appearing in the path have corresponding description information; it is detected whether a functional attribute is present in the query attributes.

8. The method of claim 1, wherein the ratio calculation method P/P is used_jAnd obtaining the RESTful degree of the REST API to be detected in the field to which the REST API belongs.

Images