Synergy!データベースAPI は外部のシステムから、Synergy! のデータベース（マスター・履歴）の読み出し、登録・更新・削除などを簡単に行うことができる API です。
Synergy! の豊富な機能を生かしたシステム開発を簡易・短期間に行うことが可能です。

API をご利用いただく場合、事前に Synergy! の利用登録が必要になります。
利用登録がまだお済みでない方は Synergy! 公式ページよりお問い合わせください。

また、API の利用には Synergy! データベース API 契約規定 が適用され、API を利用すると契約規定に同意したものとみなされます。

管理画面上の API 管理からクライアント認証キー、クライアントシークレットの発行を行なってください。 発行時アクセス可能な IP アドレスを設定することで、指定した IP アドレス以外からのリクエストを制限することができます。 ※アクセストークン取得（auth.paas.crmstyle.com）のアクセスは、指定した IP アドレスからのリクエスト制限の対象外です。

Synergy!データベースAPI にアクセスするためには、リクエストヘッダーに発行したクライアント認証キー、クライアントシークレットを使用して取得したアクセストークンを付与する必要があります。
アクセストークンは事前に Synergy! 認可サーバ (https://auth.paas.crmstyle.com/oauth2/token) から OAuth 2.0 のクライアント・クレデンシャルズフローにより取得します。
アクセストークンには有効期限が設定されており、切れるまでアクセストークンは有効です。Synergy!データベースAPI へアクセスするたびにアクセストークンを取得しないようにしてください。
アクセストークンの取得には、IPアドレス単位で1分間あたり最大100リクエストの上限を設けていますので、その上限を超えた場合はエラーを応答します。（HTTPステータスコード：429）
上限エラーとなった場合、再度アクセストークンを取得するには1分程度時間をあけてからアクセスする必要があります。

アクセストークン取得

リクエストURL

https://auth.paas.crmstyle.com/oauth2/token

リクエストヘッダー

リクエストパラメーター

scope一覧

リクエストサンプル

AUTHHEADER=`echo -n ${CLIENT_ID}:${CLIENT_SECRET} | base64 -w0`  
SCOPES="db:apidefinition:design db:openapi:read db:record:execute"
curl -i -X POST \
  -H "Authorization: Basic ${AUTHHEADER}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  https://auth.paas.crmstyle.com/oauth2/token \
  -d "grant_type=client_credentials&scope=${SCOPES}&audience=https://db.paas.crmstyle.com"

レスポンス

レスポンスは JSON 形式で返却されます。

レスポンスサンプル

{
  "access_token": "{Access Token}",
  "expires_in": 3599,
  "scope": "db:apidefinition:design db:openapi:read db:record:execute",
  "token_type": "bearer"
}

レスポンス JSON プロパティ

Synergy!データベースAPI リクエスト

リクエストの際、Authorization ヘッダーにアクセストークンをセットしてください。

listApiDefinition リクエストサンプル

curl -X GET \
  -H "accept: application/json" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  https://db.paas.crmstyle.com/apis/apidefinition.database/v1/accounts/{accountCode}/apidefinitions

1. 認証情報取得

認証をご参照ください。

2. Record 定義登録

データモデルを OpenAPI V3 Schema 形式で定義し ApiDefinition.putApiDefinition から定義を登録します。
定義を登録することで Synergy! データベースに項目が作成され API に紐付けされます。Synergy! データベースに作成されている既存項目を定義登録に使用したい場合、既存項目を API に定義する を参照してください。

3. Record 利用

2で登録された API を Record より実行してください。

APIクライアントについて

作成された API は OpenAPI Specification で定義されています。 OpenApi より OpenAPI Document を取得することで、ご利用の開発言語に応じて API クライアントの自動生成が可能です。 コード生成ツールは OpenAPI.Tools をご参照ください。

同時リクエスト数の制限には、トークンバケットモデル（アカウントごとに、レート：150/sec、バースト：300）を採用しています。
ブロック発生時は、レスポンスコード：429 Too Many Requests を返しますので、数分後に再度お試しください。

データベースAPIのレスポンスは、対象データ件数、検索条件、システムの利用状況などにより時間がかかる場合があります。
通信タイムアウトの設定はご利用環境と用途に合わせて調整していただく必要がありますが、30秒以上に設定することを推奨します。

GUIでのログイン処理や検索処理といった利用者が再実行可能な用途については混雑中をお伝えするなど、レスポンスステータスをチェックして適切な例外処理を設けてください。
API呼び出しでは通信状況など様々な要因で一時的にエラーが発生する可能性があるため、他システム連携など必要な手続きでは適切なリトライを設け処理を担保してください。
リトライの対象として、サーバーエラー（5xx）、リクエスト数制限エラー（429）、タイムアウトなどのネットワークエラーを考慮してください。
新規登録を行うリクエストでは、適切な更新キーをAPI 定義に含めることでリトライ時の重複登録を防止することが可能です。
複数回リトライを固定間隔にした場合、アクセス集中時に呼び出し間隔が収束するため、リクエスト数制限に達し易くなる傾向があります。
リクエスト数制限回避のため、リトライ間隔は固定値ではなく徐々に間隔を長くする「エクスポネンシャルバックオフ」と、可能でしたら一定の乱数を加味する「ジッター」を設け、分散させることをお勧めします。
また、最終的にAPIを実行できなかった際に、後からトレースができるようにAPI呼び出し元で適切なログを収集することをお勧めします。

サーバ間連携用の独自の REST API を作成することができます。

ApiDefinition で作成した API 定義を OpenAPI Document 形式で参照することができます。

Synergy! 内に登録されているデータベース設定情報を参照することができます。

ApiDefinition で作成した REST API を実行することができます。

• 文字型、数値型、年月日型、タイムスタンプ型は type および format を指定することで、x-synergy-type を省略することができます。

Synergy!データベースAPI では、既に管理画面などからデータベースに設定されている項目を API に定義することができます。 対象の項目名を DatabaseDefinition から取得し、x-synergy-mapping にセットしてください。

既存項目マッピングサンプル

"spec": {
  ...
  "schema": {
    "properties": {
      "existingTxtColumn": {
        "x-synergy-mapping": "_col1",
        "type": "string"
      },
      "existingDateColumn": {
        "x-synergy-mapping": "_col2",
        "type": "string",
        "format": "date"
      },
      "existingPasswordColumn": {
        "x-synergy-mapping": "_col3",
        "x-synergy-type": "password"
      }
      "existingSingleSelectColumn": {
        "x-synergy-mapping": "_col4",
        "x-synergy-type": "singleSelect"
      }
    }
  }
}

API 定義更新時、x-synergy-select-value-definitions を使用して既存の選択型項目の選択肢を削除 / 編集すると、
意図せず選択肢定義を変更してしまうことがあります。

選択肢が変更された場合、管理画面での選択肢追加・変更を打ち消すような不整合が生じる可能性があります。
例えば、選択型項目に存在する選択肢を API 定義に含めずに更新すると、該当の選択肢は削除され、データベースに格納されている選択データも削除されます。

API定義から選択肢を管理しない場合は、x-synergy-select-value-definitionsを定義しないようにしてください。
選択肢の管理を行う場合は、API定義を更新する前に、最新の選択型項目の定義を DatabaseDefinition から取得し、 今から更新する選択肢内容が問題ないか確認してからAPI定義を更新してください。

文字化けなどの問題を避けるため、DBAPIでは以下ルールで文字変換を行っております。

データベースAPI(ver1.0.0) を実行するサンプルプログラムです。

• PHP