2011-09-13 72 views
9

我正在使用WcF身份驗證服務創建WCF Web服務,我需要的第一組功能是管理客戶端的收件箱。客戶端將由認證確定。我是否正確設計了這個WCF RESTful接口?

這是我嘗試在API的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列表存檔

我這樣做對嗎?如果不是,那麼設計此接口的更好方法是什麼?

+0

聽起來像讀和未讀可以成爲你的第二個網址的一部分? 'https:// api.mydomain.com/v1/inbox/mark/read'和'https:// api.mydomain.com/v1/inbox/mark/unread' –

+0

它們應該是兩個單獨的函數還是一個函數的參數(這在RESTful API中更常見)? – Jason

+0

如果你按照我的建議做,那麼這將是兩個終點是正確的?如在兩個URL中。但系統可以用相同的方法處理它們。 –

回答

0

關於閱讀/未閱讀部分 我不認爲你需要一個職位。我認爲你需要把方法 https://api.mydomain.com/v1/inbox/messageId/Read https://api.mydomain.com/v1/inbox/messageId/Unread

後創建一個新的記錄時,需要和您要更新

對於保存部我我同意。只記得歸檔過程的結果。

1

Martin Fowler的有理查德森成熟度模型,它需要做一個RESTful服務什麼的good summary。 Jan引用了Roy Fielding的一篇文章,但除了超媒體之外,還有一些步驟需要關注(和HATEOAS)。

參照Richardson model,我覺得你的API將需要一些改變才能到「三級」(咄咄duhhhh)。 /v1/inbox/messages集合看起來很合理,只有支持GET表明它是用戶的只讀資源。但POST ing操作和ID到/v1/inbox/mark/v1/inbox/archive只是通過HTTP隧道RPC樣式服務 - article中的「級別0」。

我建議像下面這樣作爲一個天真的,非超媒體(即「2級」)API:

  • 要檢索的所有消息的摘要信息列表(在所有文件夾):

    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代替PUT,表示部分更新。

  • 脫穎而出的注意

其他的事情是:

  • 超媒體反應和媒體類型。坦率地說,這可以由其他人更好地解釋(例如REST In Practice書或同一作者的InfoQ Coffee Cup example),但總之,您的回答應該向客戶指出可能從響應到最近的請求可能採取的其他行動,並允許他們從一個URI中發現整個API。舉個例子,上面有一個文件夾集合的含義。如果GET /v1/messages/1234返回:

    <message subject="Subject" unread="true" id="1234" folder="inbox" > 
        Message text here. 
    
        <link rel="folder" href="http://api.mydomain.com/v1/folders/inbox" /> 
    </message> 
    

    則客戶將有一個URI的一個具體的例子來試穿的OPTIONS,和什麼可能是有一個好主意。

  • 響應代碼和內容:200 OK是顯而易見的。如果用戶未被授權查看特定消息,則迴應403 Forbidden,如果消息標識不存在,則回覆404 Not Found。每當您返回錯誤時,請向客戶指出如何糾正其請求(如果可能的話)。