Design and imagination of building self-describing RESTFul API system

Source: Internet
Author: User

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:

    1. API usage, topics, and introduction

    2. API parameters and the meaning of each parameter

    3. The return result of the API and the meaning of each field

    4. 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:

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:

    1. Docker's Dockerfile transforms the build process into code to make the running environment more replicable

    2. 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

Contact Us

The content source of this page is from Internet, which doesn't represent Alibaba Cloud's opinion; products and services mentioned on that page don't have any relationship with Alibaba Cloud. If the content of the page makes you feel confusing, please write us an email, we will handle the problem within 5 days after receiving your email.

If you find any instances of plagiarism from the community, please send an email to: and provide relevant evidence. A staff member will contact you within 5 working days.

A Free Trial That Lets You Build Big!

Start building with 50+ products and up to 12 months usage for Elastic Compute Service

  • Sales Support

    1 on 1 presale consultation

  • After-Sales Support

    24/7 Technical Support 6 Free Tickets per Quarter Faster Response

  • Alibaba Cloud offers highly flexible support services tailored to meet your exact needs.