在API設計中,端點(Endpoint)和參數是讓使用者與服務進行互動的關鍵元素。端點可以理解成API的地址,每個端點代表一個特定的資源或功能;參數則是用來補充細節,告訴API需要處理哪些資料或以什麼方式操作,端點與參數設計的好壞,會直接影響API是否容易使用與維護。
端點的命名通常遵循RESTful架構風格,以資源為核心,使用名詞來描述。例如,/users
表示使用者資源,/orders
表示訂單資源,可以在端點後加上識別符號,例如 /users/{id}
代表特定使用者,/orders/{id}
代表特定訂單,結構清晰、層次分明能讓開發者一眼就理解端點的用途。
參數設計則可以分為兩類:路徑參數(Path Parameter)與查詢參數(Query Parameter)。
/products/123
代表編號123的商品。/products?category=book&sort=price
,能查詢分類為書籍的商品並依價格排序。除了結構與命名,資料格式的一致性也是重要考量,大部分API使用JSON作為傳遞格式,因此欄位名稱應簡單明確,資料型別要統一。例如日期欄位應統一使用ISO 8601格式,布林值應明確表達為 true
或 false
,避免因為不同格式造成解析困難。必要與選填的參數也應清楚區分,並在文件中加以說明,以降低API使用出錯的機會。