1.0 specification, technical documents, | standard API documentation

background

As the business develops, more and more projects support the platform.

At the same time, in order to make the business system clearer, the system business will be split horizontally and vertically stratified from the architecture system of the whole platform project, generating a series of platforms and subsystems, and using interfaces for data interaction.

As the business grows, there will be more and more interface documentation.

So what’s the pain point?

The code and the documentation do not match, the code interface is updated, the documentation is not updated, and the content and form of the interface documentation are so colorful that it is not easy to understand.

One minute of lifting, three hours of docking

To address these pain points, we have defined the following interface documentation specification as a guide for writing API interfaces so that you can write well-regulated API documentation.

API Documentation Overview

What is the API

Application Programming Interface (API) is a predefined function that connects the client and the server. It provides applications and developers with the ability to access a set of routines based on certain software or hardware without accessing the source code. Or understand the details of the inner workings.

What is an API document

API documents are detailed descriptions of API functions, usage, version and other information for API users. API documents increase the ease of use of API and other public constraints for API developers.

What is a good API document

Good API documentation must satisfy the following requirements for users:

• Easy to learn:

It is well documented and provides as many examples as possible, followed by industry and international standards, so that callers with experience and background can get started quickly.

For example, to define the country code, use the isO-3316 country code standard country code, China is “CN”, rather than make up a “CHI” to avoid misunderstanding.

• Easy to use:

There are no complex procedural and business details to the reader, as long as it is easy for the reader to learn.

Flexible APIS allow sorting by field, customizable paging, sorting, filtering, and more. A complete API means that the expected functionality is included.

• Difficult to misuse:

Detailed error messages, users can read the document to understand how to use the API and error, will not be “surprise” when calling the API.

• compatibility

API upgrades should consider backward compatibility, and documentation should also consider consistency.

For example, try to avoid mandatory parameters in version 1, make them optional in version 2, and so on.

• real-time

Documents, in turn, should be considered for updating as version changes, consistent with the service.

Avoid client requests for new interfaces based on old documents that are inconsistent with expectations.

API Documentation Directory

The standard interface document directory format is defined below:

Revision history 2. Interface Description 3. Basic service Access Information service information 4. Request and Returned Parameters Request Parameters Returned Parameter 5. Success and Exception Example Success Example Request Parameters Returned Parameter Exception Example Request Parameters Returned Parameter 6. Status code Error code Service codeCopy the code

Sample API documentation

A brief example of a standard interface document is provided below, and you can refer to this structure and example when creating an API document.

Revision history

The revision history of this document is listed below in reverse order.

In principle, any changes to the definition, constraints, and functionality of the API should be reflected in the revision history below, and it is strongly recommended to upgrade the version after the interface changes and ensure as much backward compatibility as possible (that is, clients can use the functionality if they have not updated the API).

Interface description

The following is a brief description of the document, which briefly describes the capabilities provided by the interface, the business scenarios covered, and the related system roles.

Service access

This section describes the interface type (such as RPC and HTTP), interface address, and client configuration.

The basic information

The service information

To request an RPC interface, add the following description.

• Service AppId: AppPAyService

• interface: com. Example. Pay. TransferService

• Method: Transfer

• maven rely on

SAPSHOT version is used when developing joint tuning, and the latest RELEASE version needs to be replaced before logging on to UAT

<dependency>
  <groupId>com.example.pay</groupId>
  <artifactId>pay-transfer</artifactId>
  <version>Latest RELEASE</version>
</dependency>
Copy the code

• Interface definition

public interface TransferService {
    Response<Result> transfer(Request request);
}
Copy the code

The data model

A complete data model definition should include:

• Path and query string parameter model
• Request body parameter model
• Response volume parameter model

Below lists the request and returns the parameter data model defines the sample, including the kind of “variable name | | the required” is composed of a parameter, the minimum data set (MDS), that is, a complete parameter definition should have at least the three information.

Request parameters

Returns the parameter

Docking sample

Successful example

Request parameters

{
    "mchId":"1000008"."amount":900
}
Copy the code

Returns the parameter

{
    "txnId":"2019022018061909"."status":0
}
Copy the code

Abnormal sample

Request parameters

{
    "mchId":"100000"."amount":100
}
Copy the code

Returns the parameter

{
    "status":1
    "errorCode":404."desc":"Merchant does not exist"
}
Copy the code

Status code

Error code

The business code