REST API - URL related rules

Introduction

本篇文章主要整理URL命名上的一些規則。

Rules

Rule: Lowercase letters should be preferred in URI paths

第一條規則就是要讓URI接使用小寫字元為優先。會有這條規則的主因是RFC 3986定義了URL會有大小寫之區別，且lowercase為使用上之慣例，因此使用小寫可以避免user連到非預期的內容中。可以參考這兩篇reference:

如果在現有的軟體中，已經有支援大寫的內容，可以透過回應301讓client redirect到正確的頁面中即可。另需要注意的是，query parameter也算是在URL的一環中，所以也有大小寫的區分，URL中只有protocol(schema)與host是case-insensitive，但標準化為lowercase。

Rule: Hyphens (-) should be used to improve the readability of URIs

Rule: Underscores (_) should not be used in URIs

這兩個rules主要在討論多個文字組合的可讀性怎做比較合適。與Camel Case一同考慮的話，首先是雙擊選取文字，以下三者是不是只有Hyphens有辦法做到將兩個文字分開選擇呢? (若你要提供的是一次選擇就另當別論了)

  • twoTokens
  • two_tokens
  • two-tokens

而CamelCase比起Hyphens+lowercase，更容易讓user誤輸入非預期的大小寫而導入非預期的內容，這也是為什麼Hyphens被推薦的原因。但需注意的是，如果考慮的是在API回應內容的情境中，Hyphens比起Camel Case用在javascript的client時，就不會這麼吃香了。

Reference