API定義書

■ 基本情報

項目	値
IF名	○○連携
FROM	○○システム
TO	Salesforce
タイミング	随時
メソッド	POST
URI	`https://マイドメイン.my.salesforce.com/services/sample/`
概要	APIの概要を記述

補足

下記のメソッドがサポートされます。
- GET ― リソースを取得する
  - 情報を取得するために用いられます。サーバー上のリソースが変更される場合は原則使用しません(既読や参照日時等を除く)。
- POST ― リソースを作成する
  - ユーザ登録や記事投稿など、新しい情報を登録するために利用されます。リソースの更新にはPUT、PATCHを使います。
- PUT ― リソースを作成・更新する
  - URIで指定したリソースを更新します。もともとのリソースを完全に上書きするときに使用します。リソースの一部を更新する場合はPATCHを使用します。URIで指定したリソースが存在しない場合は新規作成しますが、データの修正にPUTをつかい、新規に作成する場合にPOSTを使用するのが一般的です。
- PATCH ーリソースの一部変更(Winter'21)
  - リソースの一部を更新するときに用いられます。
- DELETE ― リソースを削除する
  - URIで指定したリソースを削除するために用いられます。
URIについて

■ リクエストヘッダ

No	項目名	必須	値	備考
1	Authorization	○	Bearer xxxxx	xxxxxはアクセストークン
2	Content-Type	○	application/json	固定値

補足

GET、DELETEはリクエストボディがないためContetn-Typeを設定しません。
POST、PUTではXMLよりJSONを使うようにします。現在APIの主流はJSONとなっているようです。
- XMLを使用する場合は、Content-Typeをapplication/xmlにします。

■ リクエストボディ

No	項目名	属性	最大バイト数	必須	値	備考
1	name	String	255	○	商品名
2	quantity	Integer	5	○	数量(0～99999)

補足

GET、DELETEはリクエストボディは有りません。
APIを公開する前に、項目名はよく確認すること。特に大文字小文字。

■ ステータスコード

No	ステータス	備考
1	200	正常応答
2	400	クライアント起因のエラー
3	500	サーバーエラー

補足

Salesforce標準のステータスコードはこちら。

■ レスポンスヘッダ

No	項目名	必須	値	備考
1	Content-Type	○	application/json;charset=UTF-8	固定値

補足

レスポンスの形式は極力XMLよりJSONを選択します。
- XMLを使用する場合は、Content-Typeをapplication/xmlにします。

■ レスポンスボディ(200)

|No|項目名|和名|属性|最大バイト数|値|sf項目名|sfラベル名|
|:-:|:--|:--|:--|:--|:--|:--|:--|:--|
|1|name|顧客名|String|255||Account.Name|顧客名|
|2|lastContactDate|最終活動日|String|10|yyyy-MM-dd形式|Account.LastContactDate__c|最終活動日|
|3|customers|取引先責任者リスト|List(Object)|-|対象がない場合は空のリスト|Account.Contacts|取引先責任者|
||>>customerCode|顧客番号|String|8||Contact.CustomerCode__c|顧客番号|
||>>Name|取引先責任者名|String|80||Contact.Name|取引先責任者名|

補足

null(null)と空文字('')は区別するようにします。
日付と日時はISO-8601の拡張形式で表現するようにします。
- 2020-11-01
- 2020-11-01T10:00:00.000+09:00
項目名は、JSONなのでキャメルケースをが自然な気がしますが、スネークケースを採用しているAPIも多いので、どちらでも良さそうです。
APIを公開する前に、項目名はよく確認すること。特に大文字小文字。
レスポンスデータは極力階層化しないようにします。

■ レスポンスボディ(エラー)

No	項目名	和名	属性	最大バイト数
1			List(Object)
	>>errorCode	エラーコード	String	255
	>>message	エラーメッセージ	String	255

OAuth認証

API設計書にOAuthの認証方法も追記します。ここでは例として「OAuth2.0 JWT ベアラーフロー」を使用します。

■ 基本情報

項目	値
認証方式	OAuth2.0 JWT ベアラーフロー
メソッド	POST
URL	`https://マイドメイン.my.salesforce.com/services/oauth2/token`
備考	① 予め自己署名デジタル証明書(.crt)をSalesforceにアップロードする必要があります。 ② API利用時に、リクエストヘッダーに`Authorization: Bearer レスポンスのaccess_tokenの値`を追加してください。Bearerとアクセストークンの間に半角スペースが必要です。

補足

REST APIを使用するには、接続アプリケーションのOAuth範囲にapi, refresh_token, offline_accessが必要です

■ リクエストヘッダ

No	項目名	必須	値	備考
1	Content-Type	○	`application/x-www-form-urlencoded`	固定値

■ リクエストボディ

No	項目名	属性	最大バイト数	必須	値	備考
1	grant_type	String	-	○	`urn:ietf:params:oauth:grant-type:jwt-bearer`	固定値
2	assertion	String	-	○	JWTの値を設定

■ JWT

領域	項目	値	備考
ヘッダー	alg	RS256	固定値
ペイロード	iss	xxxxx	接続アプリケーションのコンシューマ鍵
ペイロード	aud	`https://login.salesforce.com`	固定値
ペイロード	sub	`sample@example.com`	Salesforceユーザ名
ペイロード	exp	`1333685628`	Oauth トークンの有効期限。UTC で測定された 1970-01-01T0:0:0Z からの秒数として表記。現在時刻から3分間のみ有効。

■ レスポンス

No	項目名	説明
1	access_token	OAuth トークン
2	instance_url	ユーザの組織のインスタンスを示す URL
3	id	ユーザを識別し、ユーザの詳細を照会するために使用できる ID URL
4	token_type	固定値「Bearer」
5	scope	範囲値のスペース区切りのリスト

参考