RESTful 接口規範

原文地址：http://www.coderli.com/translate-restful-standard-resolved

 

OneCoder最近一直在使用Restful API，最近正好看到一篇自定義restful接口規範的「拋磚引玉」得的文章，索性翻譯一下，與你們分享。

原文地址： http://java.dzone.com/articles/restful-standard-resolved  

 

最近，我正在使用RESTfull的方式構建一個web服務。儘管如今有不少的通常的指導和提示告訴你如何定義restful接口，可是卻沒有一個明確的標準或你們都接受的schema定義去遵循。

 

在網上獲取了一些信息後，我打算打破這一局面：）我打算分享一下我定義的規則和結構，而且很但願能獲得一些反饋來幫助我完善這個規則，因此，不要猶豫，請毫無留情給我指出錯誤和毛病吧。

 

高級別的模式是：

http(s)://server.com/app-name/{version}/{domain}/{rest-convention}

 

這裏，{version}表明api的版本信息。{domain}是一個你能夠用來定義任何技術的區域(例如：安全-容許指定的用戶能夠訪問這個區域。)或者業務上的緣由。(例如：一樣的功能在同一個前綴之下。)

 

{rest-convention} 表明這個域(domain)下，約定的rest接口集合。

 

單資源( singular-resourceX )

url樣例：order/  (order即指那個單獨的資源X)

• GET – 返回一個新的order
• POST- 建立一個新的order，從post請求攜帶的內容獲取值。

 

單資源帶id(singular-resourceX/{id} )

URL樣例：order/1 ( order即指那個單獨的資源X )

• GET – 返回id是1的order
• DELETE – 刪除id是1的order
• PUT – 更新id是1的order，order的值從請求的內容體中獲取。

 

複數資源(plural-resourceX/)

URL樣例:orders/

• GET – 返回全部orders

 

複數資源查找(plural-resourceX/search)

URL樣例：orders/search?name=123

• GET – 返回全部知足查詢條件的order資源。(實例查詢，無關聯) – order名字等於123的。

 

複數資源查找(plural-resourceX/searchByXXX)

URL樣例：orders/searchByItems?name=ipad

• GET – 將返回全部知足自定義查詢的orders – 獲取全部與items名字是ipad相關聯的orders。

 

單數資源(singular-resourceX/{id}/pluralY)

URL樣例：order/1/items/ (這裏order即爲資源X，items是複數資源Y)

• GET – 將返回全部與order id 是1關聯的items。

 

singular-resourceX/{id}/singular-resourceY/

URL樣例：order/1/item/

• GET – 返回一個瞬時的新的與order id是1關聯的item實例。
• POST – 建立一個與order id 是1關聯的item實例。Item的值從post請求體中獲取。

 

singular-resourceX/{id}/singular-resourceY/{id}/singular-resourceZ/

URL樣例：order/1/item/2/package/

• GET – 返回一個瞬時的新的與item2和order1關聯的package實例。
• POST – 建立一個新的與item 2和order1關聯的package實例，package的值從post請求體中得到。

 

上面的規則能夠在繼續遞歸下去，而且複數資源後面永遠不會再跟隨負數資源。

總結幾個關鍵點，來更清晰的表述規則。

• 在使用複數資源的時候，返回的是最後一個複數資源使用的實例。
• 在使用單個資源的時候，返回的是最後一個可是資源使用的實例。
• 查詢的時候，返回的是最後一個複數實體使用的實例(們)。

但願你的關注能幫助我完整這個結構並解決你可能偶然遇到的問題。

 

在下一篇文章裏，在這個結構完善以後，我將會一些技術上的樣例如何在Spring MVC3.1中，使用它。