Preface

version note version note note： please note that this restapi manual only applies to asternos v3 1 r0500 series software version basic concept of resource construction 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 https //restful api design readthedocs io/en/latest/resources html request request format of uniform resource locator (url) 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 https //www rfc editor org/rfc/rfc7230#section 2 7 http request methods 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 https //datatracker ietf org/doc/html/rfc6902 https //developer mozilla org/en us/docs/web/http/methods response response return code 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 https //developer mozilla org/en us/docs/web/http/status https //www rfc editor org/rfc/rfc2616#section 10 return value format 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 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 properties description table explanation required field 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 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 common data range description range description ethernet name ethernet0 3999 ethernet sub interface name eth0 3999 0 4094 portchannel name portchannel0001 9999 portchannel sub interface name po0001 9999 0 4094 vlan name vlan0 4094 loopback name loopback0 199 mgmt name eth0 vrf name a word starts with "vrf" notes on url path construction notes on url path construction path variables path variables in restful api urls, variables are denoted by enclosing them in curly braces (e g , /users/{userid}) path compression 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 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