Help Center> Object Storage Service> Developer Guide> Object Storage Service> Basic Concepts> REST API
View PDF

REST API

REST stands for Representational State Transfer. API stands for application programming interface. The REST API is a communication interface that is in compliance with the HTTP protocol and REST architecture style. With the REST architecture, each Uniform Resource Identifier (URI) represents a resource, so the web address must not contain verbs. A web resource can be a segment of text, an image, an audio file, a service, or any resource entity.

Characteristics of the REST architecture are as follows:

  1. Each URI represents a resource.
  2. The resource is transferred between a client and the server in a certain form.
  3. The client uses four HTTP request methods (PUT, GET, POST, and DELETE) to perform operations on server resources, and thus to implement the Representational State Transfer.

In REST, specific information or data on a network is represented by a resource, which is referenced with a uniform resource identifier (URI). Clients on a network can locate resources using uniform resource locators (URLs).

OBS uses buckets, objects, and their parameters to locate specific URL. Use URLs when you want to operate resources.

The following provides a common URL format. The parameters in square brackets ([ ]) are optional.

protocol://[bucket.]domain[:prot][/object][?param]

Table 1 URL parameters

Parameter

Description

Mandatory

protocol

Protocol used for sending requests, which can be either HTTP or HTTPS. HTTPS is a protocol that ensures secure access to resources. OBS supports both HTTP and HTTPS.

Yes

bucket

Resource path of a bucket, identifying only one bucket in OBS.

No

domain

Domain name or IP address of the server for saving resources

Yes

port

Port enabled for protocols used for sending requests. The value varies with

different servers deployed. By default, the default port is used. Each transmission protocol has a default port.

For example, the default HTTP port number is 80, and the default HTTPS port number is 443.

In OBS, HTTP port number is 5080 and that of HTTPS is 5443.

No

object

An object path used in the request.

No

param

A specific resource contained by a bucket or object. If this parameter is omitted, the bucket or object itself is obtained.

No

A request must be in HTTP 1.1 format. A request header must contain OBS-defined parameters, for example, signature information.

HTTP supports several HTTP request methods, such as GET, PUT, POST, DELETE, HEAD, and OPTIONS. A request method indicates how to access specific resources. Table 2 describes the request methods supported by the OBS REST API.

Table 2 HTTP request methods supported by the OBS REST API

Methods

Description

GET

Requests the server to return a specific resource, for example, a bucket list or object.

PUT

Requests the server to store a specific resource, for example, a bucket or object.

POST

Requests the server to store a special resource or perform a special operation, for example, part uploading or merging.

DELETE

Requests a server to delete specified resources, for example, an object.

HEAD

Requests the server to return the digest of a specific resource, for example, object metadata.

OPTIONS

The request server checks whether the user has the operation permission for a resource. The CORS needs to be configured for the bucket.

The server returns a status code and reminder information to the user. Table 3 describes the common error codes:

Table 3 OBS status code

Response Code

Description

2xx

Indicates that the server has successfully returned the requested data.

4xx

Indicates that the request sent from the client is incorrect, so the server does not create or modify data.

5xx

Indicates that an error occurs on the server, and the user does not know whether the request has been successfully sent.

For details about OBS errors, see the Object Storage Service API Reference.

Parent topic: Basic Concepts