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

Posted

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了atitit.基于http json api 接口设计 最佳实践 总结o7相关的知识,希望对你有一定的参考价值。

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

 

1. 需求:::serverand 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. client调用接口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. 需求:::serverand 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 服务client将一个装满数据的信封(包含方法和參数信息)通过 HTTP 发送到server。

server打开信封并使用传入參数运行指定的方法。

方法的结果打包到一个信封并作为响应发回client。

client收到响应并打开信封。每一个对象都有自 己独特的方法以及仅公开一个 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

methparamtok

 

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:[email protected]

转载请注明来源: 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. client调用接口overview 

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

6.1. 请求返回说明(正常情况下)

正常情况下,server会返回下述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 原则是,client和server之间的交互在请求之间是无状态的。从client到server的每一个请求都必须包括理解请求所必需的信息。假设server在请求之间的不论什么时间点 重新启动。client不会得到通知。此外,无状态请求能够由不论什么可用server回答,这十分适合云计算之类的环境。

client能够缓存数据以改进性能。

 

10.2. URI

URI仅仅代表资源的实体,不代表它的形式。

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

 

10.3. 还有一个重要的 REST 原则是分层系统。

这表示组件无法了解它与之交互的中间层以外的组件。

通过将系统知识限制在单个层,能够限制整个系统的复杂性,促进了底层的独立性。

当 REST 架构的约束条件作为一个总体应用时,将生成一个能够扩展到大量client的应用程序。

它还减少了client和server之间的交互延迟。统一界面简化了整个系统架构。改进了子系统之间交互的可见性。REST 简化了client和server的实现。

 

 

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

技术分享

以上是关于atitit.基于http json api 接口设计 最佳实践 总结o7的主要内容,如果未能解决你的问题,请参考以下文章

Atitit Atitit.软件兼容性原理----------API兼容 Qa7

基于 API 手册的 JSON 查询

Atitit.api参数传递的设计

Atitit.跨语言系统服务管理器api兼容设计

Atitit. Api 设计 原则 ---归一化

Atitit.研发管理---api版本号策略与版本控制