atitit 基于http json api 接口设计 最佳实践 总结o7

atitit.基于http  json  api 接口设计 最佳实践 总结o7

 

1. 需求:::服务器and android 端接口通讯 2

2. 接口开发的要点 2

2.1. 普通参数 meth,param, 2

2.2. 所有的参数定义 2

2.3. key,dynami key)韩式 static key? 2

2.4. 防篡改 sign 2

2.5. Encry加密 3

2.6. zip压缩:: 3

2.7. 首先压缩韩式加密??? 3

3. 选型大全:rim ,ws, http xml ,json ,RESTful  -- RPC ---ws 3

3.1. RPC 样式/ REST 样式 3

3.2. RPC的优点：：与编程语言概念对应   meth(param) 3

4. 从开发速度考虑，单个的url  json RPc更加好。。 4

4.1. json可以同步开发 4

4.2. 需要传递的参数使用无状态。。每次都需要trans tok 4

4.3. 概念简单.走十meth(para) 4

4.4. 要不要信封??? 4

4.5. http请求方式: GET/Post 4

5. 发布对外http接口：注册api接口子方法处理器（服务端） 5

5.1. 使用实现类的方法注册.. 5

5.2. 使用闭包的方式注册::: 5

5.3. 闭包DSL::: 5

6. 客户端调用接口overview 6

6.1. 请求返回说明（正常情况下） 6

6.2. 错误时返回 6

7. 全局返回码说明如下： 6

8. QA：： 7

9.  8

10. 什么是REST？ 8

10.1. 无状态：：：- 8

10.2. URI 8

10.3. 另一个重要的 REST 原则是分层系统， 8

11. RESTful架构有一些典型的设计误区。 9

11.1. 最常见的一种设计错误，就是URI包含动词。 9

11.2. 另一个设计误区，就是在URI中加入版本号： 9

12. restful的缺点：frag 9

13. ws---不能同时开发，麻烦，基于wsdl工具的没有 9

14. 参考 9

 

 

1. 需求:::服务器and android 端接口通讯

2. 接口开发的要点

2.1. 普通参数 meth,param,

2.2. 所有的参数定义

附加参数说明

参数	是否必须	说明
meth	是	调用的接口方法（ 验证，返回设备状态，反馈下载信息，播放流水上传等，各自模块定义）
Param	是	实际的参数
appid	是
secret	是	预留，可暂时不用。。 用户唯一凭证密钥，即appsecret
Sign	是	签名
Zip	非	实际参数是否压缩 为t显示为压缩状态..
Encry	非	If 加密方式这个是非空的,其他参数不生效..非加密可以空的,其他参数生效

 

2.3.  key,dynami key)韩式 static key?

accessKey ( dynami key)韩式 static key??

2.4. 防篡改 sign

普通的md5 签名已经不安全了.. 比较好的是混合签名法..

2.5. Encry加密

使用等级最高的的aes 加密法..

 

2.6. zip压缩::

当数据上传量大的时候儿,应该使用压缩

 

2.7. 首先压缩韩式加密???

 

应该首先压缩在加密... 中间要是 接收了小,解密,不对走不需要解压了..

And 加密的时候儿数据也猴..

3. 选型大全:rim ,ws, http xml ,json ,RESTful  -- RPC ---ws

3.1. RPC 样式/ REST 样式

RPC 样式的 Web 服务客户端将一个装满数据的信封（包括方法和参数信息）通过 HTTP 发送到服务器。服务器打开信封并使用传入参数执行指定的方法。方法的结果打包到一个信封并作为响应发回客户端。客户端收到响应并打开信封。每个对象都有自 己独特的方法以及仅公开一个 URI 的 RPC 样式 Web 服务，URI 表示单个端点。它忽略 HTTP 的大部分特性且仅支持 POST 方法。

 

在 RPC 样式的架构中，关注点在于方法，而在 REST 样式的架构中，关注点在于资源 —— 将使用标准方法检索并操作信息片段（使用表示的形式）。资源表示形式在表示形式中使用超链接互联。

3.2. RPC的优点：：与编程语言概念对应   meth(param)

 

4. 从开发速度考虑，单个的url  json RPc更加好。。

4.1.  json可以同步开发  

ws 要同步开发要使用wsdl,但是wsdl可视化工具很少..麻烦的..

4.2. 需要传递的参数使用无状态。。每次都需要trans tok

meth，param，tok，

 

4.3. 概念简单.走十meth(para)

4.4. 要不要信封???

韩式使用req param 做为信封...要是马信封 ,直接post,不好form 提交测试..

http://host/api.jsp？appid=APPID&secret=APPSECRET&submethod=login?m={param1:val1,param2:val2}

4.5. http请求方式: GET/Post

 

 

作者:: 老哇的爪子 Attilax 艾龙，  EMAIL:1466519819@qq.com

转载请注明来源： http://blog.csdn.net/attilax

 

 

 

5. 发布对外http接口：注册api接口子方法处理器（服务端）

主要的添加一行...HandlerChain reg(String subMeth,Handler handler);

 

 

 

5.1. 使用实现类的方法注册..

HandlerChain.reg("postPlayRec", new HandlerImp1());

 

5.2. 使用闭包的方式注册:::

   

HandlerChain.reg("postPlayRec", new Handler() {

 

@Override public Object handleReq(Object arg) throws Exception {

// attilax 老哇的爪子 is6 o7l

return " o788 test ...";

 

}

});

 

5.3.  闭包DSL:::

导入template。xml模板。。java>editor>template>>import。。。

输入api   生成一下大陀代码

 

HandlerChain.reg("postPlayRec", new Handler() {

 

@Override public Object handleReq(Object arg) throws Exception {

// attilax 老哇的爪子 is6 o7l

return " o788 test ...";

 

}

});

 

6. 客户端调用接口overview 

http://host/api.jsp？appid=APPID&secret=APPSECRET&submethod=login?m={param1:val1,param2:val2}

6.1. 请求返回说明（正常情况下）

正常情况下，服务器会返回下述JSON数据包：

{param1:val1,param2:val2}

 参数含义各模块定义。。。

6.2. 错误时返回

 会返回错误码等信息，JSON数据包示例如下（该示例为AppID无效错误）:

{"errcode":40013,"errmsg":"invalid appid" }

 

7. 全局返回码说明如下：

 每次调用接口时，可能获得正确或错误的返回码， 可以根据返回码信息调试接口，排查错误。

 

返回码	说明
-1	系统繁忙
0	请求成功
40002	不合法的凭证类型
40008	不合法的消息类型
40013	不合法的APPID
40021	不合法的版本号
40033	不合法的请求字符，不能包含\uxxxx格式的字符
40035	不合法的参数
40038	不合法的请求格式
40039	不合法的URL长度
40050	不合法的分组id
40051	分组名字不合法
41001	缺少参数
42001	超时
43001	需要GET请求
43002	需要POST请求
43003	需要HTTPS请求
44002	POST的数据包为空
45009	接口调用超过限制
45015	回复时间超过限制
46001	不存在媒体数据
46004	不存在的用户
47001	解析JSON/XML内容错误
48001	api功能未授权
50001	用户未授权该api
其他返回码	。。。。

 

 

8. QA：：

get方式发送参数是需要url编码。

 

9.  

10. 什么是REST？

REST (REpresentation State Transfer) 描述了一个架构样式的网络系统，比如 web 应用程序。它首次出现在 2000 年 Roy Fielding 的博士论文中，他是 HTTP 规范的主要编写者之一。REST 指的是一组架构约束条件和原则。满足这些约束条件和原则的应用程序或设计就是 RESTful。

10.1. 无状态：：：-

---Web 应用程序最重要的 REST 原则是，客户端和服务器之间的交互在请求之间是无状态的。从客户端到服务器的每个请求都必须包含理解请求所必需的信息。如果服务器在请求之间的任何时间点 重启，客户端不会得到通知。此外，无状态请求可以由任何可用服务器回答，这十分适合云计算之类的环境。客户端可以缓存数据以改进性能。

 

10.2. URI

URI只代表资源的实体，不代表它的形式。严格地说，有些网址最后的".html"后缀名是不必要的，因为这个后缀名表示格式，属于"表现层"范畴，而 URI应该只代表"资源"的位置。它的具体表现形式，应该在HTTP请求的头信息中用Accept和Content-Type字段指定，这两个字段才是 对"表现层"的描述。

 

10.3. 另一个重要的 REST 原则是分层系统，

这表示组件无法了解它与之交互的中间层以外的组件。通过将系统知识限制在单个层，可以限制整个系统的复杂性，促进了底层的独立性。

当 REST 架构的约束条件作为一个整体应用时，将生成一个可以扩展到大量客户端的应用程序。它还降低了客户端和服务器之间的交互延迟。统一界面简化了整个系统架构，改进了子系统之间交互的可见性。REST 简化了客户端和服务器的实现。

 

 

11. RESTful架构有一些典型的设计误区。

11.1. 最常见的一种设计错误，就是URI包含动词。

因为"资源"表示一种实体，所以应该是名词，URI不应该有动词，动词应该放在HTTP协议中

11.2. 另一个设计误区，就是在URI中加入版本号：

　　http://www.example.com/app/1.0/foo

　　http://www.example.com/app/1.1/foo

　　http://www.example.com/app/2.0/foo

因为不同的版本，可以理解成同一种资源的不同表现形式，所以应该采用同一个URI。版本号可以在HTTP请求头信息的Accept字段中进行区

 

12. restful的缺点：frag

要设置一瓦url了..不适合java开发..热部署的问题.

13. ws---不能同时开发，麻烦，基于wsdl工具的没有

14. 参考

什么是REST？以及RESTful的实现 - 51CTO.COM.htm