Shulou(Shulou.com)05/31 Report--

The content of this article mainly focuses on the example analysis of extensible OpenAPI design based on OAS. The content of the article is clear and clear. It is very suitable for beginners to learn and is worth reading. Interested friends can follow the editor to read together. I hope you can get something through this article!

With the rise of the Internet industry, the development model has been gradually transformed into micro-service autonomy: small teams develop micro-services, and then call each other through the Restful interface. Developers are increasingly eager to communicate fluently in a "mandarin" and even automate the interaction of multiple programming language systems.

The Open API Strategy (OpenAPI Initiativev) issued a statement in January 2017 and a draft implementation in February. After repeated discussions, version 3.0 of the standard API specification OAS (OpenAPI-Specification) was born in June 2017.

In the OAS 3.0 architecture, OpenAPI is defined as the following 8 modules, with yellow modules as required fields and green modules as optional fields:

The workflows of the main modules are as follows:

The following highlights the three required parts for users to obtain OAS API information:

1.1 API basic Information

Users query to obtain the basic definition and information of OpenAPI, which involves the following two modules:

L openapi

Required: required

Object type: String

Similar to the XML declaration (), it sets which specification the file should use for parsing.

L info

Required: required

Object type: Info Object

This module mainly provides metadata for API.

The following is an example of Info Object:

Title: Sample Pet Store App # must be the application name

Description: This is a sample server for apetstore. # description of the application

TermsOfService: terms of service connection for http://example.com/terms/ # applications

Contact: # contact information for application providers

Name: API Support

Url: http://www.example.com/support

Email: support@example.com

License: # the protocol followed by the application

Name: Apache 2.0

Url: http://www.apache.org/licenses/LICENSE-2.0.html

Version: 1.0.1 # application version

1.2 Target server information

Users query to get the basic definition and information of the server, which involves the following module information:

Servers

Required: required

Object type: [Server Object]

This module mainly provides connection information to the target server. If the module does not define url, it will automatically generate a Server Object with a url of / according to the specification.

For example:

Servers:

-url: https://development.gigantic-server.com/v1 # required

Description: Development server # optional, url description

1.3 API path and definition

Query the specific parameters of API, involving the remaining modules of OAS, this paper mainly introduces paths and components modules.

L paths

Required: required

Object type: Paths Object

This module mainly provides the connection information of the target server where the OpenAPI is located. If this module is not defined, a Server Object with a url of / will be automatically generated according to the specification. Through the multi-level definition, the paths/method of API is determined respectively, and the relevant information such as response code can be reused by referencing the definition in the comonents module through $ref. For request types that carry bodybodies, requestBody can provide example (or array examples), which is very flexible (you can pass in a complete example, a reference, or even an example of URL).

For example:

/ pets: # URL

Get: # method, get/post/..

Description: Returns all pets. # description

Responses: # response module

The return code of '200 characters: # is 200. You can use wildcards to define the response.

Description: A list of pets. # response description

Content: # Content field

Application/json:

Schema:

Type: array

Items:

$ref:'# / components/schemas/pet' # reference componets

L components

Required: not required

Object type: Components Object

This module mainly provides a custom field definition for each OpenAPI, and the defined objects are often referenced by a specific API in the paths:

− response responses

− parameter parameters

− sample examples

− request body requestBodies

− title headers

− Link links

− callback callbacks

− mode schemas

− Security system securitySchemes

The following is an example of Components Object:

Components:

Schemas: # Protocol definition

Category:

Type: object

Properties:

Id:

Type: integer

Format: int64

Name:

Type: string

Tag:

Type: object

Properties:

Id:

Type: integer

Format: int64

Name:

Type: string

Parameters: # Parameter definition

SkipParam:

Name: skip

In: query

Description: number of items to skip

Required: true

Schema:

Type: integer

Format: int32

LimitParam:

Name: limit

In: query

Description: max records to return

Required: true

Schema:

Type: integer

Format: int32

Responses: # return message definition

NotFound:

Description: Entity not found.

IllegalInput:

Description: Illegal input for operation.

GeneralError:

Description: General Error

Content:

Application/json:

Schema:

$ref:'# / components/schemas/GeneralError'

SecuritySchemes:

Api_key:

Type: apiKey

Name: api_key

In: header

Petstore_auth: # Authentication definition

Type: oauth3

Flows:

Implicit:

AuthorizationUrl: http://example.org/api/oauth/dialog

Scopes:

Write:pets: modify pets in your account

Read:pets: read your pets

2 how to use OAS to design extensible OpenAPI

The OpenAPI specification contains a set of mandatory guidelines on how to design REST API, starting with the protocol-first approach rather than implementation priority, so it is necessary to first design the API interface and then implement the code for the protocol interface.

How to implement an elegant API is a very challenging task. Developers need to expose API in an appropriate way with the support of huge back-end systems. In addition to word spelling, path design, etc., well-designed OpenAPI often has the following characteristics:

L single responsibility

Single responsibility is a well-known principle in software engineering. In practice, when designing an API, we should ensure that each API has a single core responsibility, and when one API responsibility changes, it should not lead to other API failures and risks. Different API in OAS can refer to multiple schema in the paths module. When we design a new API or extend the existing API function, if we find that multiple API references the same schema multiple times, we need to focus on whether each API still maintains a single responsibility.

L abstract API

The appropriate abstract API is business-independent, more generic, and easy to extend. Specific API interface design can solve specific problems, but there is a corresponding lack of scalability and universal applicability of the system, so it is necessary to analyze specific scenarios to avoid over-designed (overdesign) and under-engineering (lazy design).

For a simple example, we design an API with a paths of / dog, then the API returns information about a specific dog. If we abstractly design an API with a paths of / pet, configure dog as a parameter in the parameters of components, so that the scalability of the API is improved. Subsequent expansion of other pet businesses such as cat can be developed without changing the API path, but only need to update the parameters of component.

L convergent API

The OpenAPI provided to the user is best to support batch data processing, rather than having the user call it again and again. By considering the relationship between multiple API, let users realize the simplicity of API. For example, if it is possible for a user to need the result of API1 before calling API2, then the API provider should wrap API1 and API2. This will reduce the user's memory burden, API convergence needs to comply with the principle of least knowledge, as the user should have the least understanding of the system he is using, rather than too much involved in the details of the system, so in the design of API, in the case of meeting the needs of users, the fewer components module fields, the better. Designers tend to be unable to guarantee the principle of a single responsibility when converging API. A good design needs to strike a balance between the two and focus on the ultimate goal: to make users easy and economical to use.

L extension mechanism

Future scalability needs to be taken into account when designing API to provide support for subsequent API compatible historical API. On the one hand, it is convenient for developers to add their own functions, on the other hand, users can also participate in building an API ecology. By designing and defining OAS, we can easily design API with object-oriented and good expansibility according to OAS architecture.

L version control

Version control is actually part of the extension. In view of the fact that a large number of projects have done poorly in version control, such as arbitrary version naming, inconsistent version settings, and no standard feature iteration, it is necessary to ensure API forward compatibility when the large version number remains the same. When the large version number of API is changed, it means that there is a big change in API as a whole, which is likely to be incompatible with the previous API. At the same time, you can remind users that you need to query API update documents to adapt, otherwise users may have a variety of unpredictable failures after updating API. On the other hand, changing the minor version number means that this is a forward-compatible optimization upgrade, and users can adopt the new API in routine updates. This tacit understanding with the user can stimulate the user's enthusiasm to adopt the new version, rather than never upgrading the dependency.

L extension-oriented development

After defining the relevant information through OAS, elegant OpenAPI should focus on the configurability of API in the development process, and the implementation of API should be open to modification, so it is necessary to extract relevant configuration items such as parameter check and field length, which can be configured and modified on the premise of providing default configuration items. at the same time, new configuration items should be allowed, such as introducing variable parameter types of java, etc. In this way, when the OAS document is modified, the overall API implementation can be changed as little as possible.

Listing some of the features of elegant OpenAPI, the OAS design specification is not so much a mandatory rule as a guided framework that developers implement efficient agile iterations by following the specification.

After completing the design and development of OpenAPI, we need to host API on a suitable platform for capacity opening, excellent platform to reduce the workload of API providers, extract common capabilities to make API providers more focused on business function development. Huawei Cloud's API gateway integrates a series of functions such as monitoring, flow control and load balancing, which can provide developers with high-performance and high-availability API hosting services, and realize the rapid opening of personal and enterprise API capabilities.

Thank you for your reading. I believe you have some understanding of "sample Analysis of Extensible OpenAPI Design based on OAS". Go ahead and practice it. If you want to know more about it, you can follow the website! The editor will continue to bring you better articles!

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.