函谷物联安全系统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
    上一篇
    基本概念
    下一篇
    接口说明