openapi 技术起步

最近几个项目都涉及到api调用的问题，因为是内部调用，简单提供个restapi就ok，但是考虑到既然做了，索性就做得高大上一点，顺便对openapi框架和技术有个起步。看了一上午的网上资料，有深度的不多，要么浅尝辄止，要么是高高在上，框架太粗，有点像作报告，对我这个入门的人没有多少意义。简单总结一下。

一、url设计，这个设计好会让调用者舒服。主要是协议（建议https）、域名、版本、路径。一般的人都会讲路径是url，我认为在地址栏中从头到尾连贯起来就合并讲了。例如

https://api.jiatj.com/v1/user/list

https://api.jiatj.com/v1/user/id

主要从安全、可理解性、扩展性、友好性理解一个url设计。

二、http方法的友好应用

常见方法有如下4中

1、GET（SELECT）：从服务器取出资源（一项或多项）。

2、POST（CREATE）：在服务器新建一个资源。

3、PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。

4、DELETE（DELETE）：从服务器删除资源。

我们最常用的事get和post，但是在应用中也没有区分，很少在意，因为没有感觉到区别，除了get传的参数长度有限制。put和delete我没有用过，如果好用，我会试下delete，这样get、post、delete就能很好的完成常见数据操作。这个还是更好的语义化。

三、返回值

返回值的友好性对开发者是个福音。其中重要的要有返回码。

格式就是json了，我对xml一直不太喜欢，尽管我2002年就实践了用xml+xlst来做ui。

四、Hypermedia API

借用了别人的说法，其实就是从api直接暴露出文档，让开发者方便了解api的内容和调用方法。

五、安全

上面多事友好性的问题，这个就是实实在在不容马虎的事了。我找到一个开源库pac4j，没用呢，不好说。初步就想用openid来做了，以后或许增加oAuth。

六、高级

容错、集群、审计...暂时不考虑。