Question

我正在使用WcF身份验证服务创建WCF Web服务，我需要的第一组功能是管理客户端的收件箱。客户端将由身份验证确定。

这是我尝试REST的REST设计：

https://api.mydomain.com/v1/inbox/messages (GET)

使用可选的搜索过滤器

返回收件箱中的结果页面

计数 - 每页记录数
页面 - 开始
排序 - （可选）字段以排序
搜索 - （可选）要搜索的文字

https://api.mydomain.com/v1/inbox/mark (POST)

标记一条或多条已读或未读的消息

操作 - MarkRead或MarkUnread
MessageIDs - 要标记的消息ID列表

https://api.mydomain.com/v1/inbox/archive (POST)

归档一条或多条消息

MessageIDs - 要归档的消息ID列表

我这样做了吗？如果没有，那么设计这个界面会有什么更好的方法呢？

Answer 1

Martin Fowler拥有Richardson成熟度模型的good summary以及制作RESTful服务所需的条件。 Jan参考了Roy Fielding的一篇文章，但除了超媒体（和HATEOAS）之外，还有一些步骤需要处理。

参考Richardson model，我认为您的API需要进行一些更改才能达到“Level 3”（duh duh duhhhh）。 /v1/inbox/messages集合看起来很合理，只支持GET表示它是用户的只读资源。但POST和/v1/inbox/mark的{{1}}操作和ID仅通过HTTP隧道传输RPC样式的服务 - article中的“级别0”。

我建议使用以下内容作为一个天真的，非超媒体（即“2级”）API：

要检索所有消息的摘要信息列表（在所有文件夹中）：
```
/v1/inbox/archive
```
响应：
```
GET /v1/messages HTTP/1.1
Host: api.mydomain.com
```

要检索完整讯息：

content-type: text/xml

<?xml version="1.0"?>
<messages>
  <message subject="Subject" unread="true" id="1234" folder="inbox" />
  <message subject="Hello, world" unread="false" id="24" folder="inbox" />
  ...
</messages>

响应：

GET /v1/messages/1234 HTTP/1.1
Host: api.mydomain.com

编辑邮件（例如将其标记为已读并将其移至存档文件夹）：
```
content-type: text/xml

<?xml version="1.0"?>
<message subject="Subject" unread="true" id="1234" folder="inbox">
  Hi, this is the message.
</message>
```
注意：此处我有意使用POST /v1/inbox/messages/1234 HTTP/1.1 Host: api.mydomain.com content-type: text/xml <?xml version="1.0"?> <message id="1234" unread="false" folder="archive" />代替POST来表示部分更新。

其他需要注意的事项是：

超媒体响应和媒体类型。坦率地说，其他人（例如REST In Practice书籍或同一作者的InfoQ Coffee Cup example）可以更好地解释这一点，但简而言之，您的回答应该向客户表明从回复中可能有哪些其他行动可能。他们最近的请求，并允许他们从一个URI发现整个API。例如，上面有文件夹集合的含义。如果PUT返回：
```
GET /v1/messages/1234
```
然后客户端将有一个具体的URI示例来尝试<message subject="Subject" unread="true" id="1234" folder="inbox" > Message text here. <link rel="folder" href="http://api.mydomain.com/v1/folders/inbox" /> </message>，并且可以了解可能存在的内容。
响应代码和内容：OPTIONS很明显。如果用户未被授权查看特定消息，则回复200 OK，如果消息ID不存在，则403 Forbidden。每次您返回错误时，请向客户提供一些指示，说明如何更正其请求（如果可能的话）。

Answer 2

关于读/未读部分我认为你不需要帖子。我觉得你需要把方法 https://api.mydomain.com/v1/inbox/messageId/Read https://api.mydomain.com/v1/inbox/messageId/Unread

创建新记录时需要发布并且您想要更新

对于存档部分我同意。只需记住返回归档过程的结果。

Answer 3

当遇到这样的问题时，Roy的POST很有帮助：http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

因此：专注于定义媒体类型，而不是将客户端耦合到预定义的URI集。他们不需要注册，有用，BTW。

也许也会看到http://www.nordsc.com/ext/classification_of_http_based_apis.html#http-type-one

我是否正确设计了此WCF RESTful接口？

3 个答案: