URL Encode

在寫 RESTful API 的測試案例時，遇到需要在 URL 路徑上寫空白的問題
如果使用 URLEncoder，空白會被編碼成 +，然後在 Jersey 端 + 並不會被編回空白。
簡單查了一下，實際上這個問題是誤用，URLEncoder 事實上是用在 URL 參數的工具
而把空白編成 + 則是 application/x-www-form-urlencoded 的標準作法。

因此，真正的問題在於不該使用 URLEncoder 去編碼 URL 路徑
但如果是片段的 URL，又沒辦法直接使用 new URI() 的樣子～
可以參考 [2] 的回應，使用 new URI(null, xxx, null).toASCIIString()。

另外，如果某個 Path 變數需要帶有 /，則可以手動用 String.replace() 方法，把 / 置換成 %2f"。
至少這樣在 Jersey 上是不會錯，但不保證所有的情境都可以這樣就是了 [3]。

參考資料

1. Path parameters with a plus (+) sign is not decoded
2. How to get absolute path with proper character encoding in Java?
3. Is a slash (“/”) equivalent to an encoded slash (“%2F”) in the path portion of an HTTP URL

使用 Maven 建立 Jersey 專案

當想要新建一個使用 Jersey 的 RESTful 的專案時，可以利用 Maven 直接產生範例 [1]

mvn archetype:generate -DarchetypeArtifactId=jersey-quickstart-grizzly2 \
-DarchetypeGroupId=org.glassfish.jersey.archetypes -DinteractiveMode=false \
-DgroupId=com.example -DartifactId=simple-service -Dpackage=com.example \
-DarchetypeVersion=2.23

從上述的官方範例中，執行後會自動產生 groupId 為 com.example、artifactId 是 simple-service
並且會先建好 com.example 這個 package 的檔案（包含 src 目錄以及 pom.xml）
之後以 eclipse 來說就直接 import 到 eclipse 裡面，就可以開始增加自己需要的東西了。

另外紀錄一件小事，因為最近在 Windows 上習慣用 PowerShell，但上述的語法卻一直不能使用
研究了一段時間之後才發現，錯誤的並不是語法本身，而是在 PowerShell 上必須加上引號 [2]
例如：

mvn archetype:generate "-DarchetypeArtifactId=jersey-quickstart-grizzly2" \
"-DarchetypeGroupId=org.glassfish.jersey.archetypes" "-DinteractiveMode=false" \
"-DgroupId=com.example" "-DartifactId=simple-service" "-Dpackage=com.example" \
"-DarchetypeVersion=2.23"

參考資料：

1. Jersey - Chapter 1. Getting Started
2. Maven 3: Maven in 5 minutes “mvn archetype:generate…” command NOT WORKING

推薦的 RESTful API 最佳實踐

想要設計好的 RESTful API，所以花了些時間找了一些文章看
（其實也只不過是去 Google「rest api design best practice」而已）
找到兩篇看完覺得我被說服了的文章
推薦有想要好好設計 RESTful API 的朋友可以參考看看。

參考資料：

1. Best Practices for Designing a Pragmatic RESTful API
2. RESTful Service Best Practices - Recommendations for Creating Web Services (PDF) 

WADL：描述網站的 REST 介面的文件

WADL 是 Jersey 會自動產生出來的文件，可以從文件中看到每個 REST 介面使用的 method、接受的資料類型、介面的操作網址等等。

網址是 http://<host_name>/<project_name>/<prefix>/application.wadl
其中 HOST_NAME 是網站的網域名稱、PROJECT_NAME 是專案名稱、PREFIX 是在 web.xml 裡面定義的 REST 介面的入口。

參考資料：
1、Chapter 15. WADL Support

使用 Tomcat + Jersey 建立 RESTful 服務

用了好一段時間的 RESTful，但還沒有自己從全白的 Linux 架起來過 XD
記錄一下，要用 Jersey 需要以下四個套件：

• asm-3.1.jar
• jersey-core-1.1.2-ea.jar
• jersey-server-1.1.2-ea.jar
• jsr311-api-1.1.jar

缺少的話 Jersey 會跑不起來，啟動 Tomcat 時就會噴一堆 Exception ~XD