abstract

API design principles:

• Controlling the granularity and number of API s
• Naming should follow the principle of simplicity, readability and uniformity.
• Prioritize API design, then code

Say one more thing: In order to develop more efficiently and save the cost of writing documents, these popular projects, such as microservices and agile development, use Swagger to generate descriptions for API services.

URL Design [for Backend Development]

HTTP Specification

The verb currently has two HTTP methods for CRUD operations.

GET: Read
 POST: New (Create,Update,Delete)
PUT: Update
 PATCH: Update, usually a partial update
 DELETE: Delete (Delete)

Naming Specification

• concise

• readable

Swollen API

Interface Number Control

Return Value Specification

• It is forbidden to return invalid fields and expose the underlying information while increasing the communication cost for front-end personnel.As shown in the following figure:
  

API Interface Comment Specification

HTTP status code

Common Status Codes

2xx: Operation successful
 4xx: Client error
 5xx: server error

Full status code, portal: HTTP Series: HTTP Status Code

2xx status code
 200 Request (or Processing) Successful
 201 Request (or Processing) Failed
 
4xx status code
 Bad Request: The request parameters are incomplete or incorrect.
Unauthorized: Unauthorized identity.
Forbidden: The user has been authenticated, but does not have the required permissions to access the resource.
Not Found: The requested resource does not exist or is not available.
Method Not Allowed: The user has been authenticated, but the HTTP method used is not within his privileges.
Gone: The requested resource has been transferred from this address and is no longer available.
Unsupported Media Type: The return format requested by the client is not supported.For example, the API can only return JSON format, but the client requires XML format.
Unprocessable Entity: The attachment uploaded by the client cannot be processed, causing the request to fail.
Too Many Requests: Client requests exceeded the limit.
 
5xx status code
 In general, the API does not disclose server details to users, so only two status codes are sufficient.
Internal Server Error: The client request was valid and an unexpected event occurred while the server was processing.
Service Unavailable: The server cannot process requests and is typically used for site maintenance status.

API Return Format Specification

Request format for API

http://{domain name}/v1/{module}/{action}
Domain name: https://localhost:5011 or http://localhost:5010 or https://api.stonecontact.com
 Module: controller name, such as user.
Action: Functions implemented by each module.For example: add, delete, etc.
  
The specific format of the front-end components is regulated by the components of the website where you are hungry.
Document description is detailed in Swagger
 Server return status code is based on the HTTP StatusCode object of.NET Core, which is not enough to be extended

API return format

• The response level directory contains three fields as follows: code, message, data

{
 "code": 200,
 "message": "", 
 "data":    
}

• Server Exception Format

{
 "code": 500,
 "message": "Internal request error!",
 "data": 0
}

• Validation returns error format

{
    "code": 400,
    "message": "Validation errors",
    "data": [
        "'Color Name' Cannot be empty.",
        "ColorName is mandatory.(Length:0-50)",
        "'Color Name_ CN' Cannot be empty."
    ]
}

• List Format

{
  "code": 200,
  "message": "Operation success.",
  "data": {
    "grid": [
      {
        "colorID": 5,
        "colorName": "White",
        "pri": 0,
        "updateTimeTag": "2019-07-11T01:11:12.8490797Z",
        "colorName_CN": "white"
      },
      {
        "colorID": 6,
        "colorName": "Red",
        "pri": 0,
        "updateTimeTag": "2019-07-11T01:11:12.8496838Z",
        "colorName_CN": "gules"
      },
      {
        "colorID": 7,
        "colorName": "Multicolor",
        "pri": 0,
        "updateTimeTag": "2019-07-11T01:11:12.8496915Z",
        "colorName_CN": "blend"
      }
    ],
    "recordCount": 19
  }
}

• Permission Format

{
 "code": 401,
}

• Return a single object

{
    "code": 200,
    "message": "Operation success.",
    "data": {
        "colorID": 4,
        "colorName": "Brown",
        "pri": 0,
        "updateTimeTag": "2019-07-11T01:06:20.0629948Z",
        "colorName_CN": "brown"
    }
}

• Tree Format

{
  "code": 200,
  "message": "Operation success.",
  "data": [
    {
      "id": 365,
      "text": "Stone Blocks",
      "pid": 0,
      "expanded": true,
      "leaf": true,
      "children": [
        {
          "id": 366,
          "text": "Marble Blocks",
          "pid": 365,
          "expanded": true,
          "leaf": false,
          "children": null
        },
        {
          "id": 367,
          "text": "Granite Blocks",
          "pid": 365,
          "expanded": true,
          "leaf": false,
          "children": null
        }
      ]
    },
    {
      "id": 172,
      "text": "Stone Tiles & Slabs",
      "pid": 0,
      "expanded": true,
      "leaf": true,
      "children": [
        {
          "id": 173,
          "text": "Alabaster Tiles & Slabs",
          "pid": 172,
          "expanded": true,
          "leaf": false,
          "children": null
        },
        {
          "id": 174,
          "text": "BlueStone Tiles & Slabs",
          "pid": 172,
          "expanded": true,
          "leaf": false,
          "children": null
        }
      ]
    }
  ]
}

• Return to DropDownList format

"code":200,
    "msg":"Success",
    "data":[
        {
            "text":"China",
            "value":"0"
        },
        {
            "text":"America",
            "value":"1"
        },
        {
            "text":"Canada",
            "value":"3"
        }
    ],

• API return code

• Internal Service Call Interface

//1.Get Call Method
//1.1 with parameters
//Dictionary<string, object> param = new Dictionary<string, object>();
//param.Add("PageSize", 20);
//param.Add("PageIndex", 5);
//var client = RestSharpHelper.GetClient("url");
//var data = client.SendRequest(RestSharp.Method.GET, param);
 
//1.2 No parameters
var client = RestSharpHelper.GetClient("http://localhost:5010/api/v1/SysColor/list");
var response = client.SendRequest(Method.GET);
if (response.StatusCode == HttpStatusCode.OK)
{
    var result = JsonConvert.DeserializeObject<ColorResult>(response.Data.Data);
}
 
//2.Post Call Method
var client2 = RestSharpHelper.GetClient("http://localhost:5010/api/v1/SysColor/list");
var response2 = client2.SendRequest(Method.POST, JsonConvert.SerializeObject(new PostModel() { }));
 
if (response2.StatusCode == HttpStatusCode.OK)
{
    var result2 = JsonConvert.DeserializeObject<ColorResult>(response2.Data.Data);
}

Last

• See here for more references to great posts: Chen Yongjia's Blog

• A little friend who likes bloggers can pay attention and compliment, keep updating Hey!