所有文档

          函谷物联安全系统 HISK

          接口规范

          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
          上一篇
          基本概念
          下一篇
          接口说明