============
**REST API**
============

以下几部分详细介绍NOS Open API的定义：第三章定义通用请求头、响应头、错误码；第四
章定义了桶相关操作API；第五章定义了对象相关的操作API；第六章定义了大对象分块上传
相关的操作API；

.. _通用请求头:

通用请求头
==========

.. list-table::
    :widths: 5 20 5
    :header-rows: 1

    * - Header	
      - 描述	
      - 是否必须
    * - Authorization	
      - | 认证信息
        | 类型：字符串
        | 默认：无	
      - Yes
    * - Content-Length	
      - | `RFC2616 <http://www.ietf.org/rfc/rfc2616.txt>`_\ 所定义的请求长度
        | 类型：字符串
        | 默认：无	
      - Conditional
    * - Content-Type	
      - | 文件的类型
        | 类型：字符串
        | 默认：无	
      - No
    * - Content-MD5	
      - | HTTP BODY MD5值base64编码后的值，与md5sum结果一致，无效的Content-MD5将返回错误：InvalidDegest
        | 类型：字符串
        | 示例：fbacf535f27731c9771645a39863328
        | 默认：无	
      - No
    * - Date	
      - | 请求的时间戳
        | 类型：字符串，格式必须符合\ `RFC1123 <http://www.ietf.org/rfc/rfc1123.txt>`_\ 的日期格式
        | 示例：Wed, 01 Mar 2012 12:00:00 GMT
        | 默认：无	
      - Yes
    * - Host	
      - | 请求资源的主机名，通常采用虚拟机风格描述
        | 类型：字符串
        | 示例：BucketName.nos-eastchina1.126.net
        | 默认：无	
      - |  Yes
    * - x-nos-entity-type	
      - | 接口返回的格式，当前支持xml和json两种格式
        | 类型：字符串
        | 示例：有效取值：json、xml
        | 默认：xml	
      - |  NO
 
 
通用响应头
==========

.. list-table::
    :widths: 5 20
    :header-rows: 1

    * - Header	
      - 描述
    * - Content-Length	
      - | 响应体的字节数
        | 类型：字符串
        | 默认：无
    * - Connection	
      - | 到服务器的连接是否打开
        | 类型：枚举类型
        | 可选值：keep-alive | close
        | 默认：无
    * - Date	
      - | 响应的时间戳
        | 类型：字符串
        | 默认：无
    * - ETag	
      - | HTTP Entity Tag，代表对象的哈希值，反应对象内容的更改情况。(`RFC2616 <http://www.ietf.org/rfc/rfc2616.txt>`_\)
        | 类型：字符串
    * - Server	
      - | 响应的服务器名称
        | 类型： 字符串
    * - x-nos-request-id	
      - | 唯一定位一个请求的ID号，主要用于某些情况下错误定位
        | 类型：字符串

错误码定义
==========

.. list-table::
    :widths: 20 20 20
    :header-rows: 1

    * - 错误码 
      - Http状态码 
      - 描述
    * - AccessDenied 
      - 403 Forbidden	
      - 权限错误，拒绝访问
    * - BadDigest	
      - 400 Bad Request
      - 提供的MD5值与服务器收到的二进制内容不匹配
    * - BucketAlreadyExist
      - 409 Conflict
      - 创建桶时，桶名已存在
    * - BucketAlreadyOwnedByYou
      - 409 Conflict
      - 创建桶时，该桶已经属于你，重复创建了
    * - BucketNotEmpty
      - 409 Conflict	
      - 尝试删的桶非空
    * - EntityTooSmall
      - 400 Bad Request
      - 提交的请求小于允许的对象的最小值
    * - EntityTooLarge
      - 400 Bad Request	
      - 提交的请求大于允许的对象的最大值
    * - IllegalVersioningConfigurationException
      - 400 Bad Request
      - 版本号配置无效
    * - IncompleteBody
      - 400 Bad Request
      - 上传的数据量小于 HTTP 头中的Content-Length
    * - InternalError
      - 500 Internal Server Error	
      - 服务器内部错误，请重试
    * - InvalidAccessKeyId
      - 403 Forbidden	
      - AccessKey找不到匹配的记录
    * - InvalidArgument
      - 400 Bad Request	
      - 无效参数
    * - InvalidBucketName
      - 400 Bad Request
      - 无效桶名称
    * - InvalidDigest
      - 400 Bad Request
      - 不是有效的Content-MD5
    * - InvalidPart
      - 400 Bad Request
      - 无效的上传块
    * - InvalidPartOrder
      - 400 Bad Request
      - 上传块的顺序有错误
    * - InvalidRange
      - 416 Requested Range Not Satisfiable
      - 请求的Range不合法
    * - InvalidRequest
      - 400 Bad Request
      - 非法请求
    * - InvalidStorageClass
      - 400 Bad Request
      - 无效的存储级别
    * - KeyTooLong
      - 400 Bad Request
      - Object Key长度太长
    * - MalformedXML
      - 400 Bad Request
      - XML格式错误
    * - MetadataTooLarge
      - 400 Bad Request	
      - 元数据过大
    * - MethodNotAllowed
      - 405 Method Not Allowed	
      - 请求的HTTP Method不允许访问
    * - MissingContentLength
      - 411 Length Required	
      - 缺少 HTTP Header Content-Length
    * - MissingRequestBodyError
      - 400 Bad Request
      - 缺少请求体
    * - NoSuchBucket
      - 404 Not Found
      - 请求的桶不存在
    * - NoSuchKey
      - 404 Not Found
      - 没有这个key
    * - NoSuchUpload
      - 404 Not Found
      - 对应的分块上传不存在
    * - NoSuchVersion
      - 400 Bad Request
      - 没有这个版本号
    * - NotImplemented
      - 501 Not Implemented
      - 该项功能尚未实现
    * - RequestTimeout
      - 400 Bad Request
      - 请求超时
    * - RequestTimeTooSkewed
      - 403 Forbidden	
      - 请求时间戳和服务器时间戳差距过大
    * - SignatureDoesNotMatch
      - 403 Forbidden
      - 请求的签名与服务器计算的签名不符
    * - ServiceUnavailable
      - 503 Service Unavailable	
      - 服务不可用
    * - TooManyBuckets
      - 400 Bad Request	
      - 创建了过多的桶

错误响应格式
============

发生错误时，服务端的响应包括

1. 相应的HTTP 3xx，4xx，5xx状态码（HTTP Status Code）
2. Content-Type:application/xml
3. XML格式的消息体

下面是一个XML格式消息体的例子

.. code-block:: xml

    <?xml version="1.0" encoding="UTF-8"?>
    <Error>
      	<Code>NoSuchKey</Code>
      	<Message>The resource you requested does not exist</Message>
      	<Resource>/myBucket/1.jpg</Resource>
    	<RequestId>123456</Request>
    </Error>
    
下面这个表格定义了错误响应的XML元素

.. list-table::
    :widths: 10 30
    :header-rows: 1

    * - 错误码	
      - Http状态码
    * - Code	
      - | 错误代码，唯一标识了一种类型的错误。
        | 类型：字符串
        | 父节点：Error
    * - Error	
      - | 错误信息元素。
        | 类型：容器
        | 父节点：无
    * - Message	
      - | 错误消息的描述，可以通过此信息来初步定位问题所在。
        | 类型：字符串
         | 父节点：Error
    * - RequestId	
      - | 该错误对应的请求ID号，请求号主要用于定位某些异常问题
        | 类型：字符串
        | 父节点：Error
    * - Resource	
      - | 包含了Bucket或Object的请求资源描述符。
        | 类型：字符串
        | 父节点：Error       

如http请求头部中指定x-nos-entity-type: json,则返回JSON格式消息体，示例如下

.. code-block:: json

    {
        "Error":{
        "Code": "NoSuchKey",
        "Message": "The resource you requested does not exist",
        "Resource": "/myBucket/1.jpg",
        "RequestId": "123456"
        }
    }

文档约定
========
:语法: 接口语法描述，使用${var}的类shell语法表示变量。
:请求参数: HTTP请求URL参数说明，参数列表以?开始，多个参数之间以&隔开。
:请求头: HTTP Reqeust Header说明，每个接口特有的请求头在接口定义中给出，通用的请求头请参阅3.1节。
:请求元素: HTTP PUT/POST请求的entity-body中的xml element说明，通常比较多的内容用请求参数不友好，需要用entity来请求。
:响应头: HTTP Response Header说明。
:响应元素: 响应的entity-body中的xml element说明。
:RFC: 文档中备注的RFC语义参考\ http://www.w3.org/Protocols/\ 对HTTP相关RFC的解释。