文档首页> > API参考> 接口使用方法> REST API介绍

REST API介绍

更新时间: 2018-12-20 17:35

公有云API符合RESTful API设计理论。REST从资源的角度观察整个网络,分布在各处的资源由URI(Uniform Resource Identifier)确定,客户端的应用通过URL(Unified Resource Locator)获取资源。URL的一般格式为:https://Endpoint/uri。其中uri为资源路径,也即API访问的路径。

公有云接口采用HTTPS传输协议,请求/响应报文使用JSON报文,媒体类型表示为Application/json。

DWS提供REST(Representational State Transfer)API。

REST从资源的角度来观察整个网络,提供创建、查询、更新、删除等方法访问服务的集群、快照等资源。

REST API请求/响应对可以分为五个部分:

请求URI

请求URI由如下部分组成。

{URI-scheme}://{Endpoint}/{resource-path}?{query-string}

尽管请求URI包含在请求消息头中,但大多数语言或框架都要求您从请求消息中单独传递它,所以我们在此单独拿出来强调。

表1 URI中的参数说明

参数

描述

URI-scheme

表示用于传输请求的协议。DWS的API都必须采用https。

Endpoint

指定承载REST服务端点的服务器域名或IP,从地区和终端节点获取。

resource-path

资源路径,也即API访问路径。从具体接口的URI模块获取,例如“v3/auth/tokens”。

query-string

可选参数,例如API版本或资源选择标准。

请求消息头

请求消息头包含如下两部分。
  • HTTP方法(也称为操作或动词),它告诉服务你正在请求什么类型的操作。DWS的REST API支持的方法如下表2所示。
    表2 HTTP方法

    方法

    说明

    GET

    请求服务器返回指定资源。

    PUT

    请求服务器更新指定资源。

    POST

    请求服务器新增资源或执行特殊操作。

    DELETE

    请求服务器删除指定资源,如删除对象等。

    HEAD

    请求服务器资源头部。

    PATCH

    请求服务器更新资源的部分内容。

    当资源不存在的时候,PATCH可能会去创建一个新的资源。

  • 可选的附加请求头字段,如指定的URI和HTTP方法所要求的字段。详细的公共请求消息头字段请参见表3
    表3 公共请求消息头

    名称

    描述

    是否必选

    示例

    Content-type

    发送的实体的MIME类型。

    application/json

    Content-Length

    请求body长度,单位为Byte。

    POST/PUT请求必填。 GET不能包含。

    3495

    X-Project-Id

    project id,用于不同project取token。

    如果是DeC的请求或者多project的请求则必须传入project id。

    e9993fc787d94b6c886cbaa340f9c0f4

    X-Auth-Token

    用户Token。请参见Token认证进行获取。

    使用Token认证该字段必选。

    -

    X-Language

    请求语言

    zh_cn

    说明:

    其它header属性,请遵照http协议。

请求消息体(可选)

请求消息体通常以结构化格式(如JSON或XML)发出,与请求消息头中Content-type对应,传递除请求消息头之外的内容。

响应消息头

响应消息头包含如下两部分。

  • 一个HTTP状态代码,从2xx成功代码到4xx或5xx错误代码。 或者,可以返回服务定义的状态码,如API文档中所示。
  • 附加响应头字段,如支持请求的响应所需,如Content-type响应消息头。详细的公共响应消息头字段请参见表4
    表4 响应消息头

    名称

    描述

    示例

    Date

    HTTP协议标准报头。表示消息发送的时间,时间的描述格式由rfc822定义。

    Mon, 12 Nov 2007 15:55:01 GMT

    Server

    HTTP协议标准报头。包含了服务器用来处理请求的软件信息。

    Apache

    Content-Length

    HTTP协议标准报头。用于指明实体正文的长度,以字节方式存储的十进制数字来表示。

    -

    Content-Type

    HTTP协议标准报头。用于指明发送给接收者的实体正文的媒体类型。

    application/json

响应消息体(可选)

响应消息体通常以结构化格式(如JSON或XML)返回,与响应消息头中Content-type对应,传递除响应消息头之外的内容。

发起请求

共有三种方式可以基于已构建好的请求消息发起请求,分别为:

  • cURL

    cURL是一个命令行工具,用来执行各种URL操作和信息传输。cURL充当的是HTTP客户端,可以发送HTTP请求给服务端,并接收响应消息。cURL适用于接口调试。关于cURL详细信息请参见https://curl.haxx.se/

  • 编码

    通过编码调用接口,组装请求消息,并发送处理请求消息。

  • REST客户端

    Mozilla、Google都为REST提供了图形化的浏览器插件,发送处理请求消息。针对Firefox,请参见Firefox REST Client。针对Chrome,请参见Postman Interceptor

文档是否有解决您的问题?

提交成功!

非常感谢您的反馈,我们会继续努力做到更好!

反馈提交失败,请稍后再试!

在文档使用中是否遇到以下问题







请至少选择或填写一项反馈信息

字符长度不能超过100

反馈内容不能为空!

提交反馈 取消

如您有其它疑问,您也可以通过华为云社区问答频道来与我们联系探讨

跳转到云社区