restful 接口是如何设计的

[Ouyangan]

刚上班没多久,经理让我写restful风格的接口文档,希望有朋友给一些建议.

[babyname]

先了解设计原则、规范，然后根据需求写吧。

[learnshare]

面向资源

[blue7wings]

http://www.ruanyifeng.com/blog/2011/09/restful.html
阮一峰的这篇页面就写得挺好，可以参考下~~

[billlee]

http://www.ibm.com/developerworks/library/ws-restful/
http://blog.luisrei.com/articles/rest.html

[Septembers]

设计文档之前先摸清楚业务

[Ouyangan]

我的情况是:之前是自学的java,时间大概有六个月,接口文档没有写过,所以感觉到有一些无从下手,谢谢楼上的朋友的建议.

[invite]

需求，需求。

[gevin]

我以前想在博客里写一下REST API设计原则的，看到下面这篇就懒得自己折腾了
https://bourgeois.me/rest/

[colincat]

@Ouyangan springMVC 内置RESTful
请参考 https://spring.io/guides/gs/rest-service/

[johnnyb]

举个例子：

```
http://~/users 用户列表
http://~/users/{id} 用户详情／编辑
http://~/users/new 新用户（news视为{id}的特殊形式）
http://~/users/{id}/roles 用户权限列表（二级资源，可以继续套用RESTfull）
```

url 中不应该出现动词，对于同一个 url 例如 http://~/users/{id}，通过 method (get/post/patch/put) 来区分是读／写操作

[zonghua]

@johnnyb 受教了，springMVC直接提供了通过目录获取参数，不知道struts2如何实现？

[anyforever]

大家API后端一般都是用什么语言开发的？

[johnnyb]

@zonghua 使用 Struts 2 开发 RESTful 服务 https://www.ibm.com/developerworks/cn/java/j-lo-struts2rest/

[sing1ee]

面向资源在实践中，只能说看上去很简单，看上去很美。但，现实很残酷，很现实。业务总是会变的越来越复杂，这个过程中，面向资源的接口会越来越混乱，逻辑不清晰，交叉比较厉害。所以，聊一聊就可以了，不用太认真。
我们使用的SpringBoot

[nullcc]

阮一峰有一篇博文《RESTful API 设计指南》写得比较浅显易懂： http://www.ruanyifeng.com/blog/2014/05/restful_api.html

[Feiox]

如果写 RESTful 文档，可以尝试一下 REST 建模语言： http://raml.org/

[minotaur]

不要出现动词，使用get post put delete，浏览器兼容是个问题

[qianlifeng]

@johnnyb
```
http://~/users 用户列表
http://~/users/{id} 用户详情／编辑
http://~/users/new 新用户（news视为{id}的特殊形式）
http://~/users/{id}/roles 用户权限列表（二级资源，可以继续套用RESTfull）
```

感觉应该是：
```
http://~/users GET/用户列表 ，POST/新用户，PUT/更新
```
一般不用下面这种形式创建吧？
···
http://~/users/new 新用户（news视为{id}的特殊形式）
···

[johnnyb]

@qianlifeng
你是对的。我这里确实没交代清楚，举的例子应该是描述如何在浏览器地址栏呈现，对应api路径其实只有 http://~/users 一个，然后通过method来判定：POST/新用户，PUT/更新，DELETE/删除。。。

[Ouyangan]

@johnnyb @qianlifeng 谢谢大家...