LoginSignup
3
3

More than 3 years have passed since last update.

@TaaaZyyy

REST Apex サービスのAPI定義書の作成メモ

Last updated at Posted at 2020-11-16

REST Apexサービスを作成する機会があったので、健忘録として記事に起こします。
社内システムの連携を想定しています。

コーディングについてはこちらに記事を作成しました。→[Salesforce] カスタムREST APIをApexで作成する | Qiita

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について
    • URLは小文字のみで表現するようにします。単語を繋げる必要があるときはハイフンまたはアンスコで区切りますが、そもそも単語を繋ぎ合わせることは極力避けます。
    • エンドポイントの設計では複数形の名詞を使用して「リソースの集合」を表します。
    • エンドポイントに動詞は極力使用しません。操作はメソッド(GET,POST,PUT,DELETE)で表します。
      • メソッドで表現しづらい動詞はエンドポイントに追加する例もあります
    • URIはどんな機能を持つURIなのかがわかるような設計を心がけます。
      • 例: データを検索する時1 GET contacts?q=
      • 例: データを検索する時2 GET accounts?country=US
      • 例: 特定のデータを取得する時 GET contacts/{レコードを指定するコード}
      • 例: Aに関連するBを取得する時 GET contacts/{レコードを指定するコード}/cases?q=
      • 例: 新しいデータを登録する時 POST contacts
      • 例: データを更新する時 PUT contacts/{レコードを指定するコード}
      • 例: 特定のデータを削除する時 DELETE contacts/{レコードを指定するコード}
    • 検索・ソート・フィルタはリクエストパラメータで行います。
      • 例: 文字列hogeを含み、作成日時で降順、連絡拒否がfalse contacts?q=hoge&sort=-createddate&optout=false

■ リクエストヘッダ

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 範囲値のスペース区切りのリスト

参考

3
3
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
3
3