接口规范

PKI API的设计采用了Restful风格,每个API功能(也可以称之为资源)都使用URI(Universal Resource Identifier)来唯一确定。对资源的请求方式是通过向资源对应的URI发送标准的 HTTP 请求,比如 GET、PUT、POST等,同时,请求需要遵守签名算法,并包含约定的请求参数。

通用约定

  • 日期格式采用yyyy-MM-dd方式,如2018-08-10
  • 时间格式采用UTC格式:yyyy-MM-ddTHH:mm:ssZ, 如2018-08-20T01:24:32Z
  • Content-type为application/json; charset=UTF-8
  • object类型的key必须使用双引号(")括起来
  • object类型的key必须使用lowerCamelCase表示

公共请求头

头域(Header) 是否必须 说明
Authorization 必须 包含Access Key与请求签名
Host 必须 包含API的域名
x-bce-date 必须 表示时间的字符串,符合时间格式要求
Content-Type 可选 application/json; charset=utf-8

公共响应头

头域(Header) 说明
Content-Type 除了ocsp接口,其他接口只支持JSON格式:application/json; charset=utf-8 ocsp接口为:application/ocsp-response
x-bce-request-id PKI后端生成,并自动设置到响应头域中

响应状态码

返回的响应状态码遵循RFC 2616 section 6.1.1

  • 1xx: Informational - Request received, continuing process.
  • 2xx: Success - The action was successfully received, understood, and accepted.
  • 3xx: Redirection - Further action must be taken in order to complete the request.
  • 4xx: Client Error - The request contains bad syntax or cannot be fulfilled.
  • 5xx: Server Error - The server failed to fulfill an apparently valid request.

请求消息体格式(HTTP Request Body)

PKI服务要求使用JSON格式的结构体来描述一个请求的具体内容。

示例

以下是一个标准的申请根证书的的请求消息体格式:

{
    "duration" : 700,
    "certRequestInfo" : {
        "country" : "CN",
        "commonName" : "root774076",
        "organization" : "Baidu",
        "unit" : "iot",
        "emailAddress" : "abc@baidu.com"
    }
}

请求返回格式(HTTP Response)

PKI服务除了ocsp接口,其他接口均采用JSON格式的消息体作为响应返回的格式。

示例

以下是一个标准的查询根证书的请求返回:

{
    "crl":"https://pkiiov.baidubce.com/v1/pki/crl?cmd=crl&format=PEM&issuer=C%3DCN%2C+O%3DBaidu+corp%2C+OU%3Dait%2C+CN%3Droot119276%2C+EMAILADDRESS%3Dabc%40baidu.com",
    "downloadUrl":"https://pkiiov.baidubce.com/v1/pki/rootcert/a9cab7e662894cc3a22df42d209a5a19/download?Authorization=bce-auth-v1%2F790b329ee5194aae868c84ce254d2f63%2F2018-07-12T03%3A31%3A31Z%2F86400%2Fhost%2F28795a15e02a9cd8735ad5221eb18727693b93369f27b2baf374443840d96cb2&userId=b1f91fbe6fe54d2eaf70ef0025f1c3c2"
}

通用错误返回格式

当调用接口出错时,将返回通用的错误格式。Http的返回状态码为4xx或5xx,返回的消息体将包括全局唯一的请求、错误代码以及错误信息。调用方可根据错误码以及错误信息定位问题,当无法定位到错误原因时,可以发工单联系百度技术人员,并提供requestid以便于快速地帮助您解决问题。

消息体定义

参数名 类型 说明
requestId String 请求的唯一标识
code String 错误类型代码
message String 错误的信息说明

错误返回示例

{
    "requestId":"49e6b63e-11e5-488e-9eb7-4e801258feb2",
    "code":"ResourceNotFound",
    "message":"The resource required is not found."
}

错误码

Code HTTP状态码 说明
AccessDenied 403 Forbidden 没有权限访问
ArgumentsInvalid 400 Bad Request 请求参数错误,请检查参数
CommonNameOccupied 400 Bad Request commonName已经存在,请修改commonName
MethodNotSupported 405 Method Not Allowed 请求的方法错误
ContentTypeNotSupported 415 Unsupported Media Type 不支持请求的Content-Type头指定的格式
NotAcceptable 406 Not Acceptable 请求的Accept头没有包含需要返回的application/json格式
InternalServerError 500 Internal Server Error 系统内部错误,请稍后重试
QuotaExceeded 403 Forbidden 超出配额,无法创建证书
ResourceNotFoundException 404 Not Found 请求的证书没有找到,请检查证书id