In today's Internet world, APIs are ubiquitous, and more and more services rely on APIs to exchange information, collaborate and connect with each other, and the experience of API development collaboration is becoming increasingly important.
There is collaboration, there is communication, the obvious way is to write a document, the use of documents to describe the purpose of the API, using methods. But how to keep the document and code synchronized is the industry's eternal problem, can be done in place few.
Is there really no way out?
This is the topic of this article, building a self-describing RESTFul API system, how to use self-describing API design, erase code and document boundaries, all code.
What is self-description
The so-called self-description is to allow the API to provide specific functionality while providing some metadata to describe the API, including but not limited to the following aspects:
API usage, topics, and introduction
API parameters and the meaning of each parameter
The return result of the API and the meaning of each field
References to related APIs or sub-APIs
By using these metadata and then aggregating and demonstrating these metadata through the right tools, we can visualize the API documentation ~
Compared to static API documentation, self-describing metadata can provide more dynamic content, can be based on parameters, the user's identity and return different content, so as to better adapt to the needs of the API users.
self-describing implementation
To be perfectly elegant, the self-describing RESTFul API system needs to start at three levels: the framework layer, the protocol layer, and the presentation layer:
Frame Layer
The framework layer is related to the specific language, through the framework of support, so that the business API and corresponding metadata can be more easily exposed through the RESTFul interface.
Protocol Layer
The protocol layer is the bridge and communication specification of the frame layer and the presentation layer, both the framework layer and the presentation layer can have multiple implementations, but the protocol layer has only one specification.
At the HTTP level, we can use the OPTIONS request to get the metadata, which is also in line with the HTTP specification definition:
This
method allows the client to determine the options and/or requirements associated with a resource, or the Capabili Ties of a server, without implying a resource action or initiating a resource retrieval.
Presentation Layer
The presentation layer makes the API's metadata more convenient for people to perceive and view by means of visualization. For example, API documentation generated by metadata is a tool for the presentation layer.
self-describing and Swagger API
There are already many RESTFul API documentation tools in the industry, such as the Swagger API and API Blueprint, which are very good productivity tools, but they do not provide self-describing scenario support.
Of course, this does not prevent us from standing on the shoulders of giants, fully reusing their results in the protocol layer and the performance layer, more convenient and quick to build their own self-describing RESTFul API system.
the idea behind
The way to do one thing millions, why choose to do so, behind is a set of ideas, the idea is to guide the principle of doing things.
The idea is "Everything is code," and so is the document.
This concept is not new, and there are many advanced productivity tools in the industry, such as:
Docker's Dockerfile transforms the build process into code to make the running environment more replicable
Well-known continuous integration tool Travis CI through. Travis-ci.yml describes the project build process
In the application of the "All Code" concept of the early stage, and then through the version control software, all changes are recorded, all the changes in the same place, all in one place modified, want to not sync is difficult.
Application Scenarios
In addition to the above mentioned API documentation scenario, the self-described RESTFul API obviously has more potential to be mined, below is a brief introduction.
Automated testing
With metadata, you can automate some basic unit testing or functional testing of all your APIs, reducing the time it takes to write your tests. More importantly, all the data needs to be maintained, such as the definition of the API model.
Service integration
The self-describing RESTFul API makes it easy to exchange information between services that depend on each other through metadata.
For example, we can implement a separate data export service, it can automatically based on the data returned by the API and corresponding metadata exported to Excel files, so that the export and data decoupling, the API to concentrate on providing data.
Automatic SDK generation
With metadata information, the SDK libraries for each language can be generated automatically, and can be dynamically generated even at run time for dynamic languages.
Design and imagination of building self-describing RESTFul API system