Overview

Introduction to REST APIs

Representational State Transfer (REST) APIs are APIs provided by Huawei OceanStor DeviceManager based on REST. Third-party developers can use the APIs to access OceanStor DeviceManager resources, such as alarms, performance data, and resource allocation information.

Characteristics of REST APIs

• As standard integration solutions, REST APIs facilitate the rapid integration of third-party systems.
• Only authorized users can use the APIs. The APIs support only Hypertext Transfer Protocol over Secure Socket Layer (HTTPS)-based access to ensure security.
• The APIs use the JavaScript object notation (JSON) data format for data interaction. The data format is simple and easy to read and write, generating less network traffic than extensible markup language (XML).

Introduction to REST

REST is a coordinated set of constraints applied to network application design and development. It reduces development complexity and improves system scalability.

Resources are a core of REST. The resources are uniquely identified by uniform resource identifier (URI), for example, /rest/${deviceId}/disk/${deviceId}.

REST employs the following standard operations to access resources:

• POST: creates resources.
• GET: queries resources.
• PUT: modify resources.
• DELETE: deletes resources.

OceanStor DeviceManager RESTful APIs provide resources using URIs. Users obtain storage device resources and storage services using the URIs accordingly.

Introduction to JSON

JSON is a lightweight data-interchange format.

The structures of the JSON are as follows:

• Object: Objects are delimited with curly brackets, for example, {key1: value1, key2: value2, ...}. You can access data using Object.key.

• Array: Arrays are delimited with brackets, for example, [element1, element2, ...]. You can access data using Object[index]. The index starts from 0.

JSON strings are more concise compared with XML, which decreases network traffic.

The following code shows how to access JSON string data:

<script type="text/javascript"> 

 var resultInfo = {"data":{"total":7,"key_2":2,"key_1":5},  

                     "code":0,  

                     "description":"Success to get alarmcount." }; 

 //Access the value of key_1. 

 var key_1 = resultInfo.data.key_1; 

</script>

Introduction to HTTP

Hypertext Transfer Protocol (HTTP) is the most widely applied Internet protocol.

It is a protocol for releasing and receiving Hypertext Markup Language (HTML) pages.

Resources requested using HTTP or HTTPS are identified by URI.

HTTPS is a secure version of HTTP. It encrypts data using Secure Sockets Layer (SSL) to ensure data security.

HTTP Request Message

An HTTP request message contains:

• Request line, for example, GET /images/logo.gif, which requests the logo.gif file from the /images directory.

• Request header, for example, Accept-Language: en.

• Empty line.
• Optional request body.

HTTP Request Methods

HTTP 1.1 defines eight methods (also called verbs) to indicate the desired action to be performed on the identified resource:

• OPTIONS: returns the HTTP methods that the server supports. This method can be used to check the functionality of a web server by requesting '*' instead of a specific resource.

• HEAD: asks for the response identical to the one that corresponds to a GET request but without the response body. This method is useful for retrieving meta-information written in response headers, without having to transport the entire content.
• GET: requests a representation of the specified resource. Requests using GET should only retrieve data and should have no other effect, for example, web applications.
• POST: requests that the server accept the data enclosed in the request message. It is often used when you submit a form or upload a file. The request may create a resource or modify an existing resource, or both.
• PUT: requests that the enclosed entity be stored under the supplied URI.
• DELETE: requests that the server delete the resource identified by Request-URI.
• TRACE: echoes back the request received by the server. This method is used for tests or diagnosis.
• CONNECT: converts the request connection to a transparent tunnel. This method is used to facilitate SSL-encrypted communication through an unencrypted HTTP proxy.

The method names are case insensitive. When the resource to be requested does not support the request method, the server returns status code 405 (Method Not Allowed). When the server cannot recognize or support the request method, the server returns status code 501 (Not Implemented).

HTTP Status Codes

The first line of all HTTP responses is called the status line. It includes the HTTP version, a 3-digit status code, and text description for the status code. The three parts are separated by space.

The first digit of a status code indicates the response type:

• 1XX Informational: The request was received by the server, and the processing continues.
• 2XX Success: The request was received, understood, and accepted successfully by the server.
• 3XX Redirection: The server must take additional actions to complete the request.
• 4XX Client Error: The request had syntax errors or could not be processed.
• 5XX Server Error: The server failed to fulfill an apparently valid request.

HTTP Request Example

A session between an HTTP client and the server is running at www.google.com. Port 80 is used.

Client request:

GET / HTTP/1.1 

Host:www.google.com  

(The first line specifies the method, resource path, and protocol version. The second line contains a header mandatory for HTTP 1.1 and specifies the host.)

Server response:

HTTP/1.1 200 OK 

Content-Length: 3059 

Server: GWS/2.0 

Date: Sat, 11 Jan 2003 02:44:04 GMT 

Content-Type: text/html 

Cache-control: private 

Set-Cookie: PREF=ID=73d4aef52e57bae9:TM=1042253044:LM=1042253044:S=SMCc_HRPCQiqy  X9j; expires=Sun, 17-Jan-2038 19:14:07 GMT; path=/; domain=.google.com 

Connection: keep-alive