TeraCLOUD REST API V2(Muramasa)

This page is automatically translated.

Introduction

TeraCLOUD REST API v2 (Muramasa) is a next-generation web interface of TeraCLOUD and a REST API designed for third-party applications.

TeraCLOUD uses HTTPS (SSL required) + WebDAV for file access, while REST API is used for management of user information and data sets. By using this REST API, the application can acquire various kinds of information of the user such as the accommodation server (but not including personal information), snapshot, create / delete data set, etc. By using it in combination with WebDAV, it becomes possible to bring various experiences to users by accessing past files and saving the current state (snapshot).

Types of REST API


 Resource name Role REST target server
 user Manipulate information related to users. Account API server api.teracloud.jp
 dataset Perform operations related to the user's data set.
Reference: About data sets
 Each node server (*) * .teracloud.jp
 mapper (planned) Manages the mapping information of the user's dataset. Each node server (*) * .teracloud.jp
 file (planned) Manipulate the file of the user. Get thumbnails and more. Each node server (*) * .teracloud.jp
 publicfile (planned) Specify the user's file release. Publish and acquire thumbnails and others. Each node server (*) * .teracloud.jp (undecided)


In TeraCLOUD, processing related to the account system is performed by the account system server (including account API server), and all the commands of WebDAV and data set resource system are performed by different node servers for each user.

A node server used by a certain user can be obtained by throwing a request to the user resource of the account API server.

The application creator first needs to throw a request to the account API server. The node server name can be obtained by the result code of the user resource, and if access to the dataset system is necessary, a request must be sent to the node server.

When the user first creates an account of TeraCLOUD, the user's node server automatically determines the accommodation destination and thereafter will not change as a rule after that. Therefore, it is possible for the application to cache the acquired node server once and continue using it.

Since the node system server operates independently, even if the API system and the web server are down, it is designed to be able to continue WebDAV service as long as even the node server is alive.

Required Credentials

In order to access the REST API, we need two credentials. When these two are conforming and correct, the API becomes available for the first time.

User ID, password

What determines the user. It is used for BASIC certification etc. It is the same format as authentication with ordinary WebDAV.

API KEY

A unique key determined for each application. It is used for labeling. Application developers can apply from here.

In TeraCLOUD, file transfer and so on are performed by HTTPS (SSL essential) and WebDAV protocol, so the application can access the server by performing BASIC authentication etc using the ID and password input from the user.

When using the REST API, in addition to this, a different API KEY is required for each application. This is because TeraCLOUD is planning to implement a function to revoke privileges based on an application from the application developer, enumerating or stopping what applications the user has allowed the REST API on My Page .

Therefore, API KEY needs to be filled in the application side in some way. Since it is that level of protection, we must also assume the case of leakage (there is a risk of leakage due to MITM attack etc even with SSL). However, since the role of API KEY at the present time is limited, we do not use encryption system using public key cryptosystem etc for exchange of API KEY itself, and it is a future task now.

How to give user ID and password

User ID and password can be authenticated by one of the following methods.

BASIC certification

A method using HTTP Request Header, Authorization:. Both preemptive mode and nonpreemptive mode are supported.

Session authentication (currently not implemented)

Alternate user credential (function to be released)

Since it is considered that the application always holds or temporarily holds the user ID and password of TeraCLOUD for accessing WebDAV, it is considered that the developer does not have trouble with the credentials when using the REST API. However, this user ID and password are all authorized credentials and can not follow change of login password. Some developers may feel uneasy about persistent retention in applications.

Therefore, TeraCLOUD has a concept that is permitted only within the scope of a specific application, data set, which is an alternate user credential.

However, at the present time, this function is supported only by the official backup tool, it is unpublished API because there is a possibility that the specification may fluctuate. It is scheduled to be released as soon as it is confirmed.

How to give API KEY

The API KEY can perform authentication in one of the following ways.

Method to send with HTTP Request Header

A method of sending by HTTP Request Header. Send the Request Header with X - TeraCLOUD - API - KEY:. It can be used with all REST API.

Method to send with MatrixParam

How to send by Matrix Parameter on URL. Send it with api_key = to the necessary part of the URL. It can be used with all REST API.

Since the REST Interface of TeraCLOUD is communication only with HTTPS, it does not need a special REST Client stack. However, since it is considered that easy access methods are different depending on the language to be used, the library stack, and the application programmer's development method, access at the above two methods is allowed at the present time.

Other information

Format of API KEY

Send 128 bits in hexadecimal, uppercase BINHEX.

Validity period

That request only.

Return value format

HTTP response code

The REST API of TeraCLOUD returns a meaningful result code to the HTTP response code. In principle, the 200 series is a normal termination and an error code is returned in 400 series etc etc. For this reason, in many applications, it is possible to perform error processing with only the HTTP response code.

Error codes are as follows. The following are applicable in all methods and noteworthy things are described separately in each item.

401 Unauthorized

User credentials are abnormal. BASIC certification does not pass.

403 Forbidden

Invalid API key. Or there are reasons that are not permitted for other reasons.

405 Method Not Allowed

For method calls that are not allowed. It happens when a method which is not permitted for a resource is executed.

406 Not Acceptable

When a format which can not be accepted by Accept header is requested

415 Unsupported Media Type

When requested in a format that can not be accepted by the Content-type header

500 Internal Server Error

An unavoidable error occurred in the server

501 Not Implemented

I executed an unimplemented method

503 SERVICE UNAVAILABLE

A temporary error occurred in the server

Entity (Body) section

In the case of the GET method, since the content is requested, it returns XML format or JSON format to the BODY part. Switching between XML and JSON uses Accpet of HTTP Request Header. If Accept is omitted, it is returned in JSON format. Both return the same object structure, so you can use whichever is easier to use for your application.

Example (Request response in JSON):

Accept: application / json

Example (Request response in XML):

Accept: application / xml

Also, some APIs allow jsonp to respond, but for security reasons only some APIs are supported. Of course, if it is not supported, 406 Not Acceptable is answered.

Example (Request response from JSONP):

Accept: application / javascript

About the result in the object

The object returned by Entity contains result. This result is basically 0, but sometimes it returns other return values. This is an internal result code. In the version at the present time, it is considered that the client application does not handle the error with this code, but it can be a judge in the log at the time of failure etc.