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

REST API介绍

分享
更新时间: 2019/06/20 GMT+08:00

第三方应用对公有云API的访问需经过签名认证。

公有云API符合RESTful API的设计理论。

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

REST API请求/响应可以分为如下部分:

  • 请求URI
  • 请求消息头
  • 请求消息体
  • 响应消息头
  • 响应消息体

请求URI

请求URI由如下部分组成:

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

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

表1 URI中的参数说明

参数

描述

URI-scheme

表示用于传输请求的协议。

Endpoint

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

resource-path

资源路径,也即API访问路径。从具体接口的URI模块获取,例如“/v1/{project_id}/vpcs/{vpc_id}”。

query-string

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

请求方法

HTTP方法(也称为操作或动词),它告诉服务你正在请求什么类型的操作。
表2 HTTP方法

方法

说明

GET

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

PUT

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

POST

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

DELETE

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

HEAD

请求服务器资源头部。

PATCH

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

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

请求消息头

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

名称

描述

是否必选

示例

X-Sdk-Date

请求的发生时间,格式为YYYYMMDD'T'HHMMSS'Z'。

取值为当前系统的GMT时间。

使用AK/SK认证时该字段必选。

20150907T101459Z

Authorization

签名认证信息。

该值来源于请求签名结果。

使用AK/SK认证时该字段必选。

SDK-HMAC-SHA256 Credential=ZIRRKMTWPTQFQI1WKNKB/20150907//ec2/sdk_request, SignedHeaders=content-type;host;x-sdk-date, Signature=55741b6...e1994

Host

请求的服务器信息,从服务API的URL中获取。值为hostname[:port]。端口缺省时使用默认的端口,https的默认端口为443。

使用AK/SK认证时该字段必选。

code.test.com

or

code.test.com:443

Content-Type

发送的实体的MIME类型。推荐用户默认使用application/json,如果API是对象、镜像上传等接口,媒体类型可按照流类型的不同进行确定。

application/json

Content-Length

请求body长度,单位为Byte。

3495

X-Project-Id

project id,项目编号。请参考获取项目ID章节获取项目编号。

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

如果是专属云场景采用AK/SK 认证方式的接口请求或者多project场景采用AK/SK认证的接口请求则该字段必选。

e9993fc787d94b6c886cbaa340f9c0f4

X-Auth-Token

用户Token。

获取Token,请参考《统一身份认证服务API参考》的“获取用户Token”章节。请求响应成功后在响应消息头中包含的“X-Subject-Token”的值即为Token值。

使用Token认证时该字段必选。

注:以下仅为Token示例片段

MIIPAgYJKoZIhvcNAQcCo...ggg1BBIINPXsidG9rZ

请求消息体(可选)

该部分可选。请求消息体通常以结构化格式(如JSONXML)发出,与请求消息头中Content-Type对应,传递除请求消息头之外的内容

若请求消息体中的参数支持中文,则中文字符必须为UTF-8编码。

响应消息头

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

  • 一个HTTP状态代码,从2xx成功代码到4xx或5xx错误代码,或者可以返回服务定义的状态码。
  • 附加响应头字段,如Content-Type响应消息头。
    详细的公共响应消息头字段请参考 表4
    表4 公共响应消息头

    名称

    描述

    示例

    Content-Length

    响应消息体的字节长度,单位为Byte。

    --

    Date

    系统响应的GMT时间。

    Wed, 27 Dec 2016 06:49:46 GMT

    Content-Type

    响应消息体的MIME类型。

    application/json

响应消息体(可选)

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

发送请求

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

  • cURL

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

  • 编码

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

  • REST客户端

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

分享:

    相关文档

    相关产品

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

提交成功!

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

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

*必选

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

字符长度不能超过200

提交反馈 取消

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

跳转到云社区