當我們開始從事API開發的時候，設計問題便出現了. 一個強而有力的API設計方法是API成功的關鍵要素. 設計糟糕的API會導致API濫用問題，或者更糟：API根本沒人使用 (指Web開發者).
建立和提供一個藝術品級別的API需要考慮一下幾點:
- 使用如部分資料中所描述的RESTful API原則 (Roy Fielding, Martin Fowler, HTTP 規範等).
- 參考Web巨頭的做法，例如Google, Microsoft, Facebook, PayPal 和其他大公司.
關於如何設計一個REST 風格的API這個問題，目前沒有通用答案. 而REST 風格的最佳實踐這個問題仍然處於辯論和鞏固中，這就是爲什麼這項工作很迷人的原因.
URI 命名
涉及到給項目中的資源明明時，有三種主要的命名約定方式: 駝峯命名法（CamelCase）, 蛇形命名法（snake_case）, 和 脊柱形命名法（spinal-case）. 這些命名法則類似於我們使用的自然語言，他們只是一種命名資源的方式，使用他們時要避免引入空格，撇號等特殊字符. 這些法則在編程語言中很通用，因爲他們只使用一組有限的特性爲變量命名.
駝峯命名法（CamelCase）
駝峯命名法在Java語言中很流行 !?. 它將每個單詞的首字母大寫，例如 camelCase, currentUser,等. 拋棄對這種命名法的可讀性的爭議，它主要的缺點是在大小寫不敏感的上下文中這種方式命名的不同變量來講是無效的（有些語言是忽略大小寫的，例如T-SQL的變量聲明）.
根據文檔 RFC3986 規定, URL是大小寫敏感的 (除了主機頭等信息).
實際情況中，大小寫敏感問題可能會對在Windows環境託管的API導致出現問題.
所以建議使用脊柱命名法（spinal-case） ( RFC3986 文檔中突出強調了這一點), 這種命名法也被 Google, PayPal 和其他大公司使用.
2. HTTP 方法
如前所述, 建立一個REST風格的API 的主要關鍵目標之一是使用HTTP協議作爲應用程序的協議，從而避免製作出“土造”的REST風格API（好難翻）. 因此, 我們應當系統的使用HTTP謂詞來描述對資源所要執行的操作，並且讓開發人員可以方便的處理重複的CRUD操作.
OPTIONS
描述目標資源的通信參數.
3. HTTP頭
HTTP頭的字段提供了有關請求或應答必要的信息,或者提供了有關消息體重發送的對象的信息.
HTTP消息頭有4種類型:
-
一般頭: 這些頭的字段對請求和響應消息有通用性.
-
客戶端請求頭: 這些頭的字段只能應用於請求消息.
-
服務器響應頭: 這些頭的字段只能應用於響應消息.
-
實體頭:這些頭的字段定義了有關實體正文的元信息,如果這兒沒有正文,則定義有關請求確認的資源的元信息
排序
排序是指在集合資源上的查詢結果進行排序.排序參數需要包含進行排序的字段的名字,並以逗號隔開.
搜索
搜索是一個集合的子資源.因此,搜索的結果有與資源和集合本身不同的格式.這使得我們可以添加建議,修正和與該搜索相關的其他信息.搜索提供參數的方式與過濾相同----都是通過查詢參數,但是搜索參數不需要精確的值,並且搜索參數的語言允許近似匹配.
403 – FORBIDDEN: 拒絕訪問.
404 – NOT FOUND: 找不到文件.
500 – INTERNAL SERVER ERROR: API 開發者應當避免這種錯誤. 如果這種錯誤在全局異常中被捕獲, stack trace會記錄下這個錯誤並且不會返回響應內容.
總結
REST 不是個新事物. REST 是大型應用服務器所用各式各樣獲取數據方式的一種迴歸, 通過它來強調早期的Internet，URI標準和HTTP標準（返璞歸真，阿彌陀佛）.
資源建模（指REST風格API設計）需要基於業務需求做仔細考慮, 技術開發注意事項（純粹的架構設計，可維護性等）和成本效益分析等前面已經討論過的各種各樣的方法，通過做這些以便創造出更加易於用戶體驗的API.