JSON REST服务规范

Version 1.0版本 1.0

简介

JSON REST是一个开放的规范文档,主要用于开发使用JSON数据形式的REST网站服务,,它定义了可通用的请求发送和响应的数据结构,客户可以很方便的执行由其他技术语言编译的服务,因而能够在客户和服务之间实现更好的交互。

响应的一般要求

一个兼容的JRest 服务:

  1. 必须声明content值为application/json;charset=UTF-8
  2. 正如Content-Type header所声明的,必须使用UTF-8 编码所有的响应。

服务类型

有2种类型的服务:安全服务和事务服务。安全服务不会造成服务端服务状态的改变,即使造成了一些改变,这样的改变对于用户也是不可见的。事务服务就有所不同,它会在服务端造成服务状态的改变,如需要,此变化可以追溯到服务的使用者。

一个服务是可以被用户多次调用的,但是用户调用同一服务一次和调用多次时服务进行的操作应该是一样的。

按照定义来看,安全服务属于幂等服务,事务服务被鼓励做成幂等形式,但是不是必须的。


数据模型

REST服务可以对单个或多个资源进行操作,单个资源应该以单数名词命名,资源的集合则应该以复数命名。例如,单个资源一本书可以被定义为book?id=isbn,多个资源书的集合被命名为books.


HTTP绑定

HTTP方法 路径 安全性 描述 示例
GET {单数形式链接}?id={主键} 安全 返回一条数据 GET /student?id={student no}
GET {复数形式链接}?{一个或多个参数} 安全 返回一组符合参数条件的数据 GET /students?all=all
DEL {单数形式链接}?id={主键} 事务 从数据表中移除一条数据 DEL /student?id={student no}
POST {复数形式链接}?{一个或多个参数} 事务 添加或者更新一条或多条资源,成功后会返回一个JSON格式结果 POST /student?id={student no}

安全服务

列表服务

列表服务是通过GET请求发送一系列的参数到对应的服务URI中。

            
    uri?param1=value&param2=value2...
        
保留参数

在本规范中定义以下参数:

参数名称 描述 类型 默认值
start 数据表中的索引的开始位置 从1开始的正整数 1
limit 返回的数据的最大值 正整数 10

JRest服务必须支持start和limit请求URI中的参数,这两个参数是可选的,如果未提供,start的默认值为1,limit默认值为10。start值是指该服务返回第一条数据的索引,limit值指的是服务所返回的数据的最大条目。

            
    uri?start=1&limit=5
        

服务器返回一个JSON对象,其中包含一个meta对象和一个data数组:

            
    {"meta":{"total":"100","start":"1","size":"5"},"data":[...]}

meta对象是可选的,但强烈建议将其列入。meta对象必须包含以下属性:

  1. total:记录总数
  2. start:第一条记录的索引。输入的参数相同。
  3. size:实际返回的记录总数。请注意,其值与limit可以不同,因为列表的记录数量可能比请求的要少。

事务服务

更新响应

更新响应POST或PUT请求

JRest服务必须返回如下所示最小的JSON数据:

            
    {"code":$number,"msg":"$message" }

code值是必须是数字。非0的数字表示错误,0表明该服务被成功调用且无错误。code值应该唯一地确定一个错误条件。

msg值是可选的,应包含错误原因信息。

其它数据可以插到上述的数据结构中,它必须是"msg"的值。

目录请求

目录请求通过GET方式发送到服务器。通过URI传参。

            
    uri?param1=value&param2=value2...