はじめに

最終更新日: 2022.07.14

FANSHIP Management APIについて

FANSHIP Management API は、有償オプション機能となり、ご利用には、別途お申込みが必要です。
営業担当・もしくはサポートまでお問い合わせください。


FANSHIP Management API ご利用にあたっての注意事項

以下内容をご一読ください。

利用制限について

リクエストの制限事項についてをご参照ください。

User-Agentへの情報追加のお願い

ご利用状況のお問い合わせをいただいた際、ログの特定を迅速におこなうため、User-Agentヘッダの追加をお願いいたします。
例）

GET /mapi/3.1/info/ HTTP/1.1
Host: ${hostname}
User-Agent: MyPortalApp-recommend-PUSH/1.2 (Linux 4.9.30; Python-requests 2.1.12) iRidge,inc

リクエストについて

FANSHIP Management API へのリクエストは、HTTP プロトコルの GET メソッドまたは POST メソッドでおこないます。 なお、httpsリクエストにのみ対応しており、httpリクエストには対応しておりません。

API ごとにリクエスト先の URL と使用可能なメソッド、必要なリクエストパラメータが定められています。

リクエストボディには次の形式の JSON オブジェクトを使用します。 POSTメソッドでも、GETメソッドでも、通常のクエリーパラメータは用いず、リクエストボディとしてJSONオブジェクトを送信します。

リクエストボティの例
{
  "key1": value1,
  "key2": value2
}

リクエストパラメータの文字コードには UTF-8 を、改行コードには CR+LF または LF を使用してください。

リクエスト先ホスト名について

ホスト名は、ご契約時に弊社からご連絡いたします。



互換性

本 API は、新機能追加などのため予告なく変更される場合があります。
予告なく変更される可能性がある機能は以下の通りです。
本 API をご利用の際は、以下の変更があることを前提としてご利用ください。

互換性の基本方針

これまで許容されていたリクエストは、変更があっても許容され続けます（ただし、文書化されていない項目・機能を利用していないこと）。
一方、これまで許容していなかったリクエストが許容される場合があります。

リトライについて

ネットワークやクラウドインフラ起因の問題により、APIが500系エラーを返す場合があります。そのようなケースにおいて、リトライ処理の考慮を推奨しております。

API リクエスト(リクエストボディ、リクエストヘッダーの両方)

  • 指定が必須ではない項目が新たに追加されることがあります。
  • バリデーションルールの制約が緩和されることがあります。
  • 条件付き必須項目が追加されることがあります。ただし、必須となる条件は、変更前に許容されていたリクエストには影響を与えないものに限ります。
    • (例) type に wifi という文字列の指定を新規に許可する(バリデーションルールの制約緩和)。
      また、新規に wifissid という条件付必須項目を追加。wifissid は、type を wifi にした場合は、必須となる。
  • 新規項目が追加される際、既存項目のバリデーションルールに追加制約が発生する可能性があります。ただし、その追加制約は、変更前に許容されていたリクエストには影響を与えないものに限ります。
    • (例) 新規にdelivery_type という任意項目を追加し、delivery_type=3 (お知らせ通知のみ)を指定した場合、popup を指定してはならない。
  • 文書化されていない項目、およびその機能は、削除または変更されることがあります。

API レスポンス(レスポンスボディ、レスポンスヘッダーの両方)

  • レスポンス項目が新たに追加されることがございます。
  • リクエスト値に応じて表示有無が変わる項目について、その項目の表示条件が緩和されることがあります。
    • (例) 変更前は、type 項目を "scheduled" にした場合のみ、"send_time" 項目を返していたが、type に "instant" を指定した場合にも、送信した時刻が返されるようになる。
  • リクエストパラメータの新規追加、およびバリデーションの制約緩和などにより、新規リクエストパターンが許容されるようになった場合、そのパターンに対するレスポンスは、それまでのレスポンスフォーマットに沿わない可能性があります。
    • (例) リクエストパラメータにresponse_typeを追加し、xmlを指定した場合、json ではなく、xml が返されるようになる。
  • 失敗するリクエストのエラーレスポンスコード( HTTP ステータスコードではなく、レスポンスボディに含まれるエラーコード)は変更される可能性があります。
  • 文書化されていない項目、およびその機能は、削除または変更されることがあります。

互換性のあるアップデートにより、影響が出てしまう例

  • 文書化されていない項目をリクエストパラメータに指定していると、期待するレスポンスにならない可能性があります。
  • リクエストパラメータのキーが動的に決まるプログラムにしている場合、文書化されていないキーを指定してしまう可能性があり、結果、期待するレスポンスにならない可能性があります。
  • リクエストURLには、末尾に/がつきます。末尾に/がつかない場合の動作は変更される可能性があります。
  • エラーレスポンスコードは変更される可能性があるため、エラーレスポンスコードにより、後続処理を分岐している場合、後続処理が変わる可能性があります。

API のバージョンについて

上記に当てはまらない変更がある際は仕様の変更を鑑み、十分な告知期間を設けるか、もしくはAPI のバージョンを新規に割り当てます。