Preface

此内容尚不支持你的语言。

Basic Concept of Resource Construction

RESTAPI is a resource-oriented interface design, and all interface designs are designed for resources. A simple understanding is to locate resources using a URI and describe operations using HTTP (GET, POST, DELETE, PUT, PATCH).

Resources can be grouped into collections. Each set is homogeneous; therefore, it only contains one type of resource and is unordered. Resources can also exist outside any set, and we refer to them as singleton resources. The collection itself is also a resource that can exist globally, located at the top level of the API; It can also be included in a single resource and exist as a subset. Subsets are typically used to express a certain ‘contained’ relationship.

The following figure illustrates the key concepts in RESTAPI.

The API resource model is used to describe the types of available resources, their behavior, and their relationships, as detailed in: rest api design concept.

Request

Format of Uniform Resource Locator (URL)

Uniform Resource Identifier: URI, the most common form of a URI is the uniform resource locator (URL), also known as a Web address. For example (SWITCH_IP represents the switch device IP): https: //SWITCH_IP/rest/v1/interfaces. parameter format:

Type	Parameter Option	Description
symbol	?	Parameter start character
=	Parameter assignment character
&	Connector between multiple parameters
keywords	selector	A method applied to resource collections/resource elements to filter individual attribute values of related resource elements
depth	Obtain resource depth, default to 1, which only resolve the current resource; If set to 1, its level 1 sub resources can be resolved, and so on, until up to 10 levels

Detail in:

Unified Resource Identifiers(rfc7230)

HTTP Request Methods

Rest API v3 uniformly uses JSON format as the request and response data format.

Method	Operation	Description
GET	obtain	Retrieves the specified resource or representation. GET is a read-only operation that does not change the engine state or have any side effects.

The HTTP GET operation should not have a request body. If information is passed in a GET request, query parameters should be used instead.
Unless specified, the HTTP GET operation returns the configured state. | | POST | create | Submits data to be processed to the specified resource. The data to be processed is included in the request body. A POST operation can create a new resource.
The POST operation request contains the details of a new resource that is created in JSON.
Every POST request must include a JSON body.
For all POST operations to create a new resource, the Location header in the HTTP response contains the complete URL to be used for subsequent PUT, GET, and delete commands.
The HTTP POST response to a Create request must have a 201 return code and a Location header containing the URI of the newly created resource in the HTTP header. | | PATCH | update | Updates the specified resource with new information. The data that is included in the PATCH operation replaces the previous data.
The PATCH operation is used to modify an existing resource.
The PATCH operation cannot be used to create a new resource. | | PUT | replace | Replace the specified resource with new information. The data that is included in the PUT operation replaces the previous data.
The PUT operation is used to replace or modify an existing resource. The PUT operation cannot be used to create a new resource.
The request body of a PUT operation must contain the complete representation of the mandatory attributes of the resource. | | DELETE | delete | Deletes a resource. If you delete a resource that has already been deleted, a 404 Not Found response is returned.
The HTTP DELETE operation should not have a request body. If information is passed in a GET request, query parameters should be used instead. |
Patch Method Standards(rfc6920)
HTTPS request methods
request methods(rfc7231)

Response

Return Code

The return code is the response code, and the HTTPS response status code indicates whether a specific HTTPS request has been successfully completed. There are five types of responses: information response, successful response, redirection, client error, and server error.

Return code	Reason	Method	Description
200	OK	GET	The server successfully returned the data requested by the user, which is idempotent.
201	Created	POST/PUT	User successfully created or updated data.
202	Accepted	*	Indicates that a request has entered the backend queue (asynchronous task).
204	No Content	DELETE/PATCH	User successfully deleted or modified data.
400	InvalidRequest	POST/PUT/ PATCH	The request sent by the user has an error, and the server did not perform a new or modified data operation. This operation is idempotent.
401	Unauthorized	*	Indicates that the user does not have permission (token username, incorrect password).
403	Forbidden	*	Indicates that the user is authorized (as opposed to a 401 error), but access is prohibited.
404	Not Found	*	The request sent by the user is for a non-existent record, and the server did not perform an operation, which is idempotent.
406	Not Acceptable	GET	The format requested by the user is not available (such as JSON format requested by the user, but only XML format).
410	Gone	GET	The resource requested by the user has been permanently deleted and will no longer be available.
422	Unprocessable Entity	POST/PUT/ PATCH	When creating an object, a validation error occurred.
500	Internal Server Error	*	The server encountered an error, and the user will not be able to determine whether the request was successful.

Detail in:

Return Value Format

Unified return format in JSON format

GET operation directly returns query results.
POSTPUTPATCH DELETE operation.
Single resource operation return format

{
    status_code

    result

    module

    resource
}

The patch operation involves sub resources of the module and requires the addition of a resource field. If successful, the result returns the string OK, and if unsuccessful, the reason for the failure is returned.

Return format for batch operations:

{
    status_code   // the entire request status code, 200 indicates success for all, 207 partially succeeded, and 400 completely failed.
    results:
        [
             {
                status_code   // single operation status code
                result
                module
                resource   // the patch operation must return.
            }, ......
        ]
}

Results is an array structure that contains the operation results of a single resource.

Tree Diagrams Node Representation

Each node in a YANG module is printed as:

  <status>--<flags> <name><opts> <type> <if-features>
    <status> is one of:
      +  for current
    <flags> is one of:
      rw  for configuration data nodes and choice nodes
      ro  for non-configuration data nodes and choice nodes,
          output parameters to rpcs and actions, and
          notification parameters
      -w  for input parameters to rpcs and actions
      -u  for uses of a grouping
      -x  for rpcs and actions
      Case nodes do not have any <flags>.
    <name> is the name of the node
      (<name>) means that the node is a choice node
    :(<name>) means that the node is a case node
      If the node is augmented into the tree from another module,
      its name is printed as <prefix>:<name>, where <prefix> is the
      prefix defined in the module where the node is defined.
      If the node is a case node, there is no space before the <name>.

    <opts> is one of:
      ?  for an optional leaf, choice, anydata, or anyxml
      *  for a leaf-list or list
      [<keys>] for a list's keys
      /  for a top-level data node in a mounted module
      @  for a top-level data node of a module identified in a
        mount point parent reference

    <type> is the name of the type for leafs and leaf-lists

      If the type is a leafref, the type is printed as either
      (1) "-> TARGET", where TARGET is the leafref path,
      with prefixes removed if possible or (2) "leafref".

    <if-features> is the list of features this node depends on,
      printed within curly brackets and a question mark "{...}?"

Arbitrary whitespace is allowed between any of the whitespace- separated fields (e.g., <opts> and <type>). Additional whitespace may, for example, be used to “column align” fields (e.g., within a list or container) to improve readability.

Properties Description Table Explanation

Required Field

Abbreviation	Full name	Description
P	Parameter	Parameter
M	Mandatory	Mandatory option
O	Option	Optional
CM	Condition	Conditional mandatory option
CO	Condition Option	Conditional Optional
RO	Read-Only	Read-Only Parameter

Type / Range Field

The range field specifies constraints on the values of a node. It can use:

Regular Expressions: For precise constraints, such as ^Ethernet([1-3][0-9]{3})$ to match Ethernet names.
Numeric Ranges: For example, 1..500 indicates a range of values from 1 to 500.
Natural Language: For simpler explanations, such as “A VLAN ID between 1 and 4094”.
Enumeration Values: such as “true”, “false”.

Common Data Range Description

Range	Description
Ethernet name	Ethernet1..3999(Ethernet1..3999:1..7 when after breakout)
Ethernet sub-interface name	Ethernet1..3999.1..4094
Link-aggregation name	Lag1..9999
Link-aggregation sub-interface name	Lag1..9999.1..4094
Vlan name	Vlan1..4094
Loopback name	Loopback0..199
mgmt name	Mgmt0
vrf name	a word starts with “Vrf”

Notes on URL Path Construction

Path Variables

In RESTful API URLs, variables are denoted by enclosing them in curly braces (e.g., /users/{userId}).

Path Compression To simplify RESTful API paths and controller bindings, the following path compression rules apply: A list node is omitted from both the path and data if the enclosing container meets the following conditions:

The list is the only subnode within the container.
The container’s name is either a prefix of or the plural form of the list’s name.

Path Omission

In RESTful API URLs, case nodes do not need to be explicitly specified in the URL path or body. Only the relevant child nodes within the selected case must be included.