Che-Sheng Lin: RESTful

顯示具有 RESTful 標籤的文章。顯示所有文章

2017-11-05

Salesforce Secured Callout

在應用系統介接時，使用 Web API 是目前常見的手段；Salesforce 也提供這樣的模式，無論是扮演 service provider (使用內建的 SOAP Web Services，或是自訂 RESTful API)，或是 service consumer，都有對應的支援；其中當 Salesforce 扮演 service consumer 時，最常見的是使用 Apex 自行呼叫外部 Web API，這種呼叫模式在 Saleforce 中稱為 callout。

在安全性方面，系統介接時一般會優先討論連線方面的安全性，更嚴謹的才會觸及資料面的安全性；這邊我們只討論前者，也就是透過 TLS 對 HTTP 加密，這樣的外部呼叫稱為 secured callout。

值得注意的是：Salesforce 在實作 secured callout 時，對簽發 target service 憑證的 CA 只認可正向表列中 root CA 簽發的憑證 [1] [2]，然而這份列表有些陳舊 [3]，許多常見的 root CA 都不在列表中，例如 TWCA Global Root CA，若 target service 不是自有的服務，無法變更憑證時，可能會被迫使用未加密的 HTTP。

另外在 protocol 版本上，Salesforce 支援 TLS 1.1 與 1.2 [4]，TLS 1.0 由於可降階至 SSL 3.0 且 SSL 3.0 設計上有安全性缺陷，因此目前已停用 TLS 1.0 [5]。

除了 secured callout 外，另一個會使用到憑證的場合是：使用 Salesforce 實作自訂的網站，並掛上自家的網域名稱；這時候對於憑證的限制比前者稍微放寬，允許不是由 root CA 直接簽發的憑證。管理者可以新增所需的 intermediate CA 到 Salesforce [6]，但根源的 root CA 仍必須是列表中認可的。

至於新增 custom site 憑證到 Salesforce 時，由於這邊扮演的是 service provider，因此上傳的資訊中必須包括 private key；使用的檔案格式是 Java KeyStore，這方面的基礎知識可以參考 [7]。

[5] How do you install an Intermediate CA (SSL) for a force.com page?

[6] SSL Certificate Standards

[7] Salesforce Community Idea: Allow Self-signed Certs for Authenticating Callout Servers

[8] Making Authenticated Web Service Callouts Using Two-Way SSL

2017-10-24

Apex Serialize Objects to XML

先前的文章 [1] 中提到，Salesforce 的 REST 同時支援兩種輸出格式，XML 與 JSON；client 可以透過 HttpRequst header 中 Accept 屬性指定想要的 content type；這兩個 serialization 的過程對於 REST service 的實作者而言是完全 transparent 的，意即實作時 method 並不 return string 型別，而是直接 return sObject，由系統的 outbound messaging 機制直接處理掉。

然而對於 Apex 開發者而言，程式語言級別對 XML 與 JSON 在 serialization 的支援度就差很遠。以 JSON 為例，無論物件多複雜，要轉成 JSON string 只要一行 JSON.serialize() 就可以搞定 [2]，但是轉成 XML string 時，無論使用 XmlStreamWriter [3] 或 DOM.XmlNode [4] [5] 都需要針對物件中各個 fields 作繁瑣地處理。

為了達到快速生成 XML 字串，我們可以透過 (1) 實作一 REST service；(2) 在 Apex 中呼叫該 service，並將 HttpRequest Accept header 設定為 'application/xml' 的方式，快速從 HttpResponse.getBody() 取得 outbound messaging 生成好的 XML 字串。

概念上是走 loopback invocation 的方式，利用既有的機制，寫最少的程式，完成任務。

see also:
[1] Salesforce RESTful Services: Response Content-Type
[2] JSON Support: Roundtrip Serialization and Deserialization
[3] XML Support: Writing XML Using Streams
[4] XML Support: Reading and Writing XML Using the DOM
[5] XmlNode Class
[6] Salesforce Trailblazer Community Idea: Convert Object to XML (Serialize)

2017-10-13

Salesforce RESTful Services: Publish

當使用 Salesforce 作為 API provider 時，預設採用 OAuth 2.0 作為認證機制，如果想簡化認證過程，則可透過將 API 發佈到公開站台的方式完成，此時需要針對 site profile 進行設定。

首先要進到 site details page；在 Setup / Build / Develop / Sites，點選 Site Label 欄位 (不是 Edit 也不是 Site URL)。

Site Details page 上方有個 Public Access Settings button，點進去後可能會因為 Org 不同而出現不同畫面：

Personal Develop Org: 畫面為一個很長的表格，要設定的地方有：Enabled Apex Class Access, Field-Level Security 與 Object Permissions。

Production Sandbox Org: 分成 Apps 與 System 兩段，需設定的連結落在 Apps 裡頭，分別是 Apex Class Access 與 Object Settings。

設定的重點不外乎：service class 本身以及相關需要存取的物件欄位，因此只要分別在 Apex Class 與 Objects 中將相關權限打開即可。

see also:
[1] Public RESTful Web Services on Force.com Sites
[2] Public Access Settings for Force.com Sites
[3] Public Access Settings in Salesforce

Salesforce RESTful Services: Response Content-Type

Salesforce 實作 RESTful 時，不需額外的程式碼，系統會自動支援 2 種 response Content-Type：JSON 與 XML。

但由於回傳 XML 時，內部的 tag 名稱會代出自訂欄位與物件的名稱，並不存在於 W3C 預設 namespace 中，而 Salesforce 亦不會代為產生對應的 XML schema，因此對於某些 XML parser 來說會造成 parsing error，比較直覺的解法是繞過回傳 XML 改使用 JSON。

ps. 實際測試時，回傳的 XML 字串會設定 namespace 為 http://soap.sforce.com/schemas/class/ 開頭的 URL，但並未實際生成 XML schema。

前面說過 Salesforce 會自動支援 2 種 response Content-Type，切換的依據是根據 request header 中的 Accept 屬性。

一般瀏覽器 (Chrome, Firefox, IE) 預設的 Accept Content-Type 為 text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8，此時 Salesforce 會優先取用 application/xml。
當未設定 Accept Content-Type，或指定 Accept Content-Type 為 application/json 或空白時，Salesforce 預設會以 JSON 作為 response Content-Type。

如果想直接在 server 端指定只支援 JSON，則必須將 method 的 return type 改為 void，並自行指定 HttpResponse，填入 JSON 字串。


RestContext.response.addHeader('Content-Type', 'application/json');
RestContext.response.responseBody = Blob.valueOf('{ "result": true}');

ps. 回傳的 charset 預設皆為 UTF-8，不需要額外設定 Accept-Charset。

see also:
[1] Apex REST Methods
[2] How can I return JSON object from REST service?

2017-09-28

Salesforce Apex REST

REST 是目前實作 web API 時較為普遍的選擇，Salesforce 原生在 APEX 中也提供了這方面的支援，方便開發者自訂 API 作為系統整合使用。在 APEX 有以下 6 個 REST annotations：

值得注意的是：APEX REST annotations 中只有 RestResource 才有 urlMapping 參數，且該 annotation 為 class level；換言之：

每一個 service implementation class，針對各種 HTTP requests 類型只能有 1 個 method；不能同時宣告多個 @HttpGet methods 在 1 class 中；
Service implementation class 中的 class name 並不會浮現在 URL 中。