阿兩的筆記本 Ryoutsu's Notebook

Introduction 在設計RestAPI時，並非所有domain操作都符合CRUD；例如，model中資料的同步(sync)、有transaction的行如轉換(transfer)、搬移(move)、複製(copy)等；因此做些案例研究看是否能找尋到自己能滿意的做法。本篇文章是根據研究結果，分享針對操作(action)做resource modeling的心得。 Model the action as a service resource action本身就是一種service，如果能把它model成一個service resource，是再好不過的。最常見的例子是login/logout，可以model為sessions，以 vCloud 為例: POST https://vcloud.example.com/api/sessions DELETE https://vcloud.example.com/api/sessions 在伺服器管理的domain中，可能有像修改firmware設定、更新firmware或掃描硬體等操作，這些該如何model為resource呢? 首先是修改firmware設定，以 HPE Server Management API 為例，它將firmware種類model為一種resource，而設定是它的sub-resource: GET /Systems/1/BIOS/Settings PATCH /Systems/1/BIOS/Settings 接著是更新firmware，以Dell ASM REST API為例，使用store resource的方式去操作: PUT /ManagedDevice/firmware 最後是掃描硬體，以RHEL Virtualization為例，透過post去新增一個discover的sub-resource(task): POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/iscsidiscover HTTP/1.1 Accept: application/xml Content-Type: application/xml <action> <iscsi> <address>m...

Twitter REST API link POST collections/entries/add POST collections/entries/curate POST collections/entries/move POST collections/entries/remove 不曉得是不是因為實作的關係，它的新增或移除都表達在URI上；另外它並沒有提供HATEOAS的功能。 Youtube Data API v3 幾乎都使用controller resource來表達特別的流程， link : # Uploads a channel banner image to YouTube. POST /channelBanners/insert # Expresses the caller's opinion that one or more comments should be flagged as spam. POST /comments/markAsSpam # Uploads a custom video thumbnail to YouTube and sets it for a video. POST /thumbnails/set # Add a like or dislike rating to a video or remove a rating from a video. POST /videos/rate # Retrieves the ratings that the authorized user gave to a list of specified videos. GET /videos/getRating # Report a video for containing abusive content. POST /videos/reportAbuse # Uploads a watermark image to YouTube and sets it for a channel. POST /watermarks/set # Deletes a channel's watermark image. POST /watermarks/unset insert的部分不曉得是考量什麼特別使用了controller res...

Problem 我們使用Spring的Rest，先前為了支援X-HTTP-Method-Override，在已存在的Filter做了此功能。某天，同事發現使用apache client api操作我們的API發生了401錯誤: {"code":401,"message":"Incorrect response","links":[{"rel":"more info","href":"http://192.168.1.110:8080/TestWeb/api/documents"}]} 要發生這個問題有兩個條件， 使用Digest認證 使用X-HTTP-Method-Override 因此在我有空時，就開始追蹤這問題。 Trace Sprint Security提供了DigestAuthentationFilter負責處理Digest認證。在使用者發出第一次請求後，Spring Security在察覺未經過驗證的情況下，會透過AuthenticationEntryPoint送出請求認證資訊。而為了在認證失敗時，能夠輸出xml或json格式的錯誤訊息(可參考上方)，我們extend了DigestAuthenticationEntryPoint: public class CustomziedDigestAuthenticationEntryPoint extends DigestAuthenticationEntryPoint {   private static final Log logger = LogFactory. getLog ( JsonDigestAuthenticationEntryPoint. class ) ;   @Autowired private MessageProcessor mMessageProcessor ;   @Override public void commence ( HttpServletRequest request, HttpServletResponse response, AuthenticationExce...

原本就有接觸過Facebook Graph API，因工作關係接觸到REST，所以學習起來比較不陌生。因為網路資料相當豐富，我只記錄些自己容易忘記的部分。 RPC-Style API VS REST API Response Code URL design rules Incorrect response(401) when using X-HTTP-Method-Override HTTP Method無法表達出某些動作 Action Modeling: Case Studies Firewall issue of HTTP Delete & Put operations HTTP Delete與Put操作可能會被防火牆阻擋，經過Study有三種替代方案。 d=delete: 增加method參數去描述行為。(可參考Spring的HiddenHttpMethodFilter) Http POST + {id}/delete: 在URI多增加操作。 Request with Header X-HTTP-Method-Override=DELETE: 透過Header置換操作。(參考link) 個人覺得第三種做法比較正規些，目前知道 firebase 、oracle的OMCAB與 IBM Business Process Manager 都用這做法。 Resource Richardson Maturity Model 中文 Well-known Link Relations Long running jobs of Rest Best Practice Best Practice - Azure Best Practices for Designing a Pragmatic RESTful API 7 Rules for REST API URI Design Good Web Site 50 Most Useful APIs for Developers Top 8 web APIs bridging today’s technology Transaction Atomic Transactions for the REST of us marklogic - REST Application Developer's Guide stacko...

Introduction 本篇文章主要整理URL命名上的一些規則。 Rules Rule: Lowercase letters should be preferred in URI paths 第一條規則就是要讓URI接使用小寫字元為優先。會有這條規則的主因是RFC 3986定義了URL會有大小寫之區別，且lowercase為使用上之慣例，因此使用小寫可以避免user連到非預期的內容中。可以參考這兩篇reference: Is UPPERCASE or lowercase Better for URLS? URL Capitalization & SEO: Does It Really Matter? 如果在現有的軟體中，已經有支援大寫的內容，可以透過回應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 REST API Design Rulebook, 1st Edition, by Mark Masse Top 6 REST Naming Best Practices Google Advanced SE...

Introduction 最近同事在review REST API的例外處理程式碼時，發現某些API居然針對所有例外，都是使用400的Response code。我看到時相當訝異，也因此希望能給新人上一課，關於REST API的基礎知識。本篇文章，主要分享常見的Response Code的意義與使用時機。 Categories Http Response Code分五類， 1xx: Informational；這類屬於Protocol操作相關的回應碼。 2xx: Success；這類屬於請求有被接收的回應碼。 3xx: Redirection；這類屬於必須做進一步的動作才能完成請求的回應碼。 4xx: Client Error；這類屬於Client相關的錯誤碼，代表Client只要調整請求方式，就能請求成功。 5xx: Server Error；這類屬於Server相關的錯誤碼，代表Server發生問題無法處理請求。 從上述內容，其實就能夠得知，假如我們將所有錯誤都以4xx回應，會讓使用者誤以為是他們的問題。接下來將會針對個別種類中，常見的回應碼做說明。 1xx - Informational 1xx的種類，在目前我們提供的REST API中，並沒有這種回應碼。目前我知道的實際案例，只有在使用StartSTL與Server溝通時，Server會回應101 Switching Protocols通知我們將連線從一般連線Upgrade為TLS連線；這部分如果以後有使用到再分享。 2xx - Success 200 - OK 最常見的回應碼，代表著請求成功且包含Response Body，通常用於HTTP GET。假如用在POST，應攜帶操作結果的描述。 201 - Created 用於POST，代表資源的新增。在Response中，會包含名為Location的Header，指出新資源的URI。 202 - Accepted 通常用於非同步操作，代表著工作已被接受，但不意味著最後會成功。假如你的API會Blocking很長時間，可以使用非同步做法，可先返回202與工作相關資訊，去減少不必要的等待。 204 - No Content 代表請求成功且沒有Response Body。可用於PUT、POST與DELETE，也可以用於GET去代表資源存在但沒有內容。 206 - P...

Problem 幾年前聽到同事說:「另一個部門的XXX說我們的REST API都沒有動詞，這樣是對的嗎?」於是我們就直接把Best Practice丟給那位同事。當時做REST API只是因為別人有而要做，而不是為了某個Context而選擇REST；後來我就思考著一件事情: 「RPC-Style與REST API比起來，到底有哪些好處?」於是我花了些時間去找尋與整理資料。首先我會先說明這裡指的RPC-style API是什麼，接著我會透過Richardson Maturity Model(RMM)說明它們兩者的差異。這是我目前認為最好的比較方式。 RPC-style API 網路上許多比較，大都是針對RPC與REST；我所說的RPC-style API是基於HTTP，主要有兩點特徵: 基於operation所設計出來的API，因此URI通常像/createAccount、/getAccounts、/deleteAccount與/updateAccount。 HTTP method只會使用GET與POST，GET使用在取得資料，POST使用在新增、修改、刪除資料。 基於RMM的比較 RMM不是定義REST達到了什麼級別，而是幫助我們層層思考的一種方式( 參考 )。Roy Fielding 2008年的 某篇文章 ，給了RESTful API很嚴格的限制，也代表著Level 3只是Restful的前置條件。由於RPC-style API屬於Level 0，因此我認為用RMM來說明REST API比RPC-style好在哪裡是再適合不過的: (圖片來自於 link ) 我們可以從Level 1~Level3來分別討論: Level 1 - Resource REST API的操作是基於Resource的。這代表著Server的設計是基於Resource，而Client的操作也是基於Resource。這為Server與Client帶來一些好處: Server 物件導向程式設計的特性之一: Divide and Conquer，將一個複雜的問題分解成各個資源；把相關的操作放於同一資源當中，以達到high cohesion。 Client 第一個好處是由於Server的設計以資源為導向，這讓User很容易了解系統的Domain Concept；其次是由於這幾年REST風格的盛行...