ユーザーAPI

ここに掲載されている内容は、開発者用の技術情報です。
掲載内容以上のサポートはできません。
ご利用にあたっては十分なご理解の上での活用ください。
SuperSaaSは開発中を含むwebhookとAPIを提供するもので、それを利用するサービス、アプリケーションに責任を持つことはできません。

ユーザーAPIを用いてユーザ情報にアクセスすることが可能です。
独自のログインシステムがある場合は、その情報を基にAPIを介してSuperSaaSにアクセスし、ユーザー登録やログインなどをシームレスに連動するメソッドも提供しています。

APIはJSONもしくはXML形式でURIパラメーターを受け取り、結果をレスポンスします。

API利用の参考シーケンス

独自システムにSuperSaaSに登録可能な形でユーザー情報が存在していることが条件となります。
独自システムの既存ユーザー情報をAPIを介することで、SuperSaaSのユーザー情報として登録、更新して同期とすることが可能です。

  1. クリックターゲットとしてボタン要素Book Now作成します。
  2. クリックをトリガーとして、SuperSaaS用のユーザー情報(ログイン名とパスワードなど)をAPIに載せて実行するメソッドを構築します。
  3. APIがコールされ、ユーザー情報が未登録の場合は新規登録、登録済みである場合は情報の更新、スケジュールへのログインを行います。

ボタンをクリックするたびに情報を更新するため、独自システムで管理しているユーザー情報とSuperSaaSのユーザー情報が同期します。
ただし、あくまでボタンがクリックされることをトリガーとするため、直接のアクセスとなるブックマークやブラウザの戻る機能などAPIがコールされない場合があることに注意が必要です。
この点が問題である場合、独自システムによるユーザー情報の更新をトリガーにとする、別途のユーザー情報更新のためのAPIをコールするシステムを構築ください。
また、不測の利用の可能性がある不特定多数ではなく、独自システムで管理している既存ユーザーに対してのみ開示する仕組みであることが望ましいかもしれません。

あるいはもっとシンプルに、APIによるユーザー情報の同期は独自システムの管理機能として別途のAPIコールとし、ユーザーにはスケジュールへのログイン、リダイレクト機能の開示のみとしてAPIを活用する方法が安全であるかもしれません。

ユーザーAPIを活用する場合の参考設定

独自システムとSuperSaaSに登録されているユーザー情報が同等に格納できる環境であることが条件です。
使い方でSuperSaaSの既存ユーザー情報をAPIを介して取得し、独自システムへ反映して同期とすることも可能です。
活用方法に合わせて適時設定の参考としてください。

  • 管理画面のアクセスコントロールにある誰がログイン名を作成出来ますか?自身のサイトでログインとユーザー登録を管理を選択します。
  • e-mailアドレスをログイン名として使用してない場合は、ユーザーログイン名を作成する時どんな情報を入力しますか? e-mailアドレスもしくはログイン名を使うのチェックを外して下さい。
  • ユーザーログイン名を作成する時どんな情報を入力しますか?は利用に方法に合わせて適切なフィールドを選択して下さい。 パスワードフィールドを用いないことも可能です。
  • 追加のセキュリティ対策が必要ですか? ユーザー自身によるユーザー情報の編集を防ぐにチェックを入れる。
  • 管理画面のレイアウト設定にある あなたのURLにデフォルトとなるURLを設定します。
    ログイン無しのアクセスがリダイレクトされます。

APIを用いたログイン

APIを用いたユーザーAPIの利用は、登録もしくは更新となるため、基本的にはユーザー情報の全てをパラメーター含めます。

参考スニペット
	<form method="post" action="http://www.supersaas.com/api/users">
	  <input type="hidden" name="account" value="Your_account_name"/>
	  <input type="hidden" name="id" value="1234fk"/> <!-- A unique key to identify the user. See below -->
	  <input type="hidden" name="user[name]" value="joe@client.com"/> <!-- Any string. Needs to be unique -->
	  <input type="hidden" name="user[phone]" value="123-456-789"/>
	  <!-- values for other fields, see the bottom of the page for a list -->
	  <!-- you can add and remove fields in the "Access Control" screen -->
	  ...
	  <input type="hidden" name="checksum" value="A4E67...DFEF"/> <!-- 32 digit MD5 Hash, see below -->
	  <input type="hidden" name="after" value="schedule_name"/> <!-- where you send your user after sign on -->
	  <input type="submit" value="Book now"/>
	</form>
	

上記スニペットに関してはこちらをあなたのアカウントで参照ください。
もし、コンテンツ管理システムとしてJoomla、Drupal、Wordpressを使用しているのな場合、各モジュールのプラグインをダウンロードできます。
 ・ Joomla module
 ・ Drupal module
 ・ WordPress plugin

ユーザーID

各トランザクションごとに、認証とユーザーレコードの特定としてユニークキーとしてユーザーIDを持ちます。
キーとする内容は以下の3つが可能です。

  1. 32ビット ユニークキー:
    独自システムで用いられているデータベースのユニークなインデックス番号に適しています。
    キーは下のSuperSaaSユーザーIDと区別するため、文字列「fk」(foreign key)を付けてポストフィックスします。
  2. SuperSaaSユーザーID:
    SuperSaaSのユーザーIDは全て数字の32ビットユニークキーです。
    ユーザーレコードの新規登録時に、そのSuperSaaSユーザーIDを記録して、以後の更新セッションでキーとして用います。
  3. 文字列(50バイト):
    数字で始まらない文字列を使用します。
    数字で管理していない場合などに用いることができます。
    任意の文字列が使用できますが、ユニークであることが必須です。
    ユーザーレコードと一意である管理が必要なため、意味を持つ文字列の場合は、重複や安易な変更が行われない文字列でキーとしてください。
    氏名などはそのままでは一意になりにくく、また不意の変更も考えられます。

MD5ハッシュのチェックサムによる認証

APIは、いくつかの違うタイプの認証をサポートします。
サーバ間の通信では、HTTP、あるいはSSLを用いた基本認識ヘッダーからURIパラメーターとしてアカウント名とパスワードを送ります。
しかしながら、上記のスニペットのように、誰でも見ることのできるオープンテキスト上にパスワード記載する方法は推奨できません。

実用時には、直接的なパスワードをURIパラメーターに含めず構築します。
直接表記のパスワードを送らずに、一方向MD5ハッシュの暗号化生成でリクエストに追加します。
MD5ハッシュはアカウント名、ユーザー名、アカウントパスワード(ユーザーパスワードではありません)を含む連結文字列から生成します。
管理者以外知ることのないアカウントパスワードを含んでいるのため、可逆解読を困難にしています。
さらに、チェックサムとして訪問者名を含み、ブラウザからのAJAXコールの安全性を高めています。

殆どの言語プラットフォームが、MD5ハッシュの生成に対応しています。

参考スニペット
PHP:
$user = 'user_name@client.com';$checksum = md5("Your_account_nameYour_account_password$user")
Ruby:
checksum = Digest::MD5.hexdigest("Your_account_nameYour_account_password#{'user_name@client.com'}")

チェックサムで管理者権限の認証となり、ユーザーはログインフォームでユーザーパスワードを入力する必要はありません。
ユーザーパスワードを用いることも可能ですが、不測の露出やMD5ハッシュ解析などを避けるためにも推奨しません。
レコードが正常に作成もしくは更新された場合、ユーザーはafter要素に含まれるURLへリダイレクトされます。
指定するURLにSuperSaaSの表示用URIパラメーターを用いることで、指定のスケジュール表示へ遷移することも可能です。

単純にログインを促すボタンやリンクを提供するだけでは、ユーザー情報の同期として不安定です。
必ずしも提供されたボタンやリンクを景趣してアクセスされるとは限りません。
また、独自構築されたユーザー情報が更新されても、提供されたボタンやリンクを介するまでSuperSaaSに反映することもありません。
密に同期を望む場合は、独自システム上でも更新毎にSuperSaaSへ反映する仕組みを構築する必要があります。

単純ログイン (プログラム構築なし)

ごく単純な利用として、HTTPSでログインAPIをアクセスコールすることも可能です。
リンク先URLにパラメータを付与されたGETを用いたAPIアクセス、もしくはPOSTでパラメータを内包してAPIアクセスできます。
選択ください
スケジュールがありません
https://www.supersaas.com/api/login?account=&after=Schedule_url&user[name]=user@client.com&checksum=A4E67...DFEF
このチュートリアルは、アカウントにログインした状態で閲覧している場合、そのアカウントに関連するコードスニペットとして動的に変換されて表示されます。
ログインする

リクエストのヘッダーにOrigin要素が含まれている場合、サーバーは適切なCORSヘッダーを追加します。
この場合、ブラウザ内のAJAX呼び出しから要求が送信されます。
SSL暗号化(https)接続を介してブラウザからリクエストを送信することを強く推奨します。

ユーザーAPIの概要

ユーザーAPIはRESTfulです。
Ruby on Railsのアクティブリソースのように、適切に書き込まれたライブラリとなっています。
各コールには、URIパラメーターとしてアカウントとパスワードを追加するか、基本認識ヘッダー(GET、POST、PUT、DELETEなど)を利用して認証します。
たとえば、http://supersaas.com/api/users?account=YourName&password=secretのようにコールします。
また前述の通り、MD5ハッシュを用いたチェックサムを利用する事もできます。
さらにセキュリティーのために、SSLを介したアクセスによるコールも可能です。

新規ユーザーの作成

/api/users.jsonに、JSON形式のユーザー情報をURIパラメーターしてHTTP POSTすることで新しいユーザーを作成することができます。
パラメーターとするフィールド情報は必ずURLエンコードするようにご注意ください。
フィールド情報の概要は後述を参照ください。

POST /api/users   (SuperSaaS will assign a key)
POST /api/users/{id}   (You provide your own key in the format 9999fk)

成功した場合、ステータスコード201(Created)がレスポンスされます。

レスポンスヘッダのLocation要素に、後でユーザーを取得するために使用できるURLが含まれています。
例:Location: http://www.supersaas.com/api/users/1234.xml
作成したオブジェクトのSuperSaaSユーザーID(上の例の場合ID:1234)は、このURL情報から取得することができます。

メールアドレスが無効など、バリデーションエラーが発生した場合、ステータスコード422 (Unprocessable Entity)となりエラーメッセージがレスポンスされます。

ユーザー情報のキーが既存である場合、APIコールは登録ではなく既存情報の更新となります。
duplicate=raiseをURIパラメーターに追加することで、既存の更新を行いません。
ただし、この場合もステータスコード422 (Unprocessable Entity)がレスポンスされます点にご注意ください。

ユーザー情報のキーにピリオドなど機能的な文字列が含まれる場合、正常な動作が行われません。
機能的な意味で危険な文字列を含む場合、{}で囲むことで、単なる文字列として扱うことも可能です。
例:/api/users?id={id}

データのフォーマット

ユーザー情報を構成するフィールドは、管理画面のアクセスコントロールで設定されます。
ログイン名は必須のフィールドとなります。
それ以外のフィールドは選択可能で、登録時に内容が指定されていない場合、デフォルトの値(通常はブランク)が設定されます。

フィールド概要
name必須ログイン名です。最大50バイトの制限があります。
e-mailをログイン名としている場合はメールアドレスとなります。
email選択可e-maiアドレスです。e-mailをログイン名としている場合は使用されません。
password選択可ユーザーのログインパスワードです。
full-name
address
mobile
phone
選択可氏名、住所、携帯電話、電話番号です。
それぞれUTF-8の文字列として格納できます。
country選択可2文字のISO 3166-1の国名コードとして格納できます。
field-1
field-2
super-field
選択可2つのカスタムフィールドおよびスーパーバイザフィールドの内容です。フィールド名ではありません。
credit選択可保有ポイント・クレジットの値が格納されます。
role選択可権限情報が格納されます。
3: ユーザー (default)
4: Superuser
-1: Blocked user
webhook選択可webhook=trueが設定されている場合、アカウントに接続されているウェブフックトリガーとなります。

レスポンスされたXMLには、上記のものに加え次のフィールドが含まれます。
フィールド概要
idユーザー登録時に付与される一意なSuperSaaSユーザーIDです。
fk32ビット ユニークキーを指定した場合にユーザに割り当てたキー(foreign key)です。
created-onユーザーが登録された時間(UTC)です。

使用例

SuperSaaSに新しいユーザ情報を登録します。
独自システムのユーザー情報の管理番号から、ユーザーIDを32ビット ユニークキーで登録したものとして、「fk」を付与した管理番号567を指定してコールしています。
POST /api/users/567fk.xml
HTTP基本認証を用いてヘッダーにアカウント名とパスワードを送信し、次の内容を含めます。
<?xml version="1.0"?>
<user>
   <password>secret</password>
   <full-name>Full Name</full-name>
   <name>user@example.com</name>
</user>
{
  "password": "secret",
  "full_name": "Full Name",
  "name": "user@example.com"
}

成功するとステータスコード201 (Created)が返ります。レスポンスに内容はありません。
もしパラメーターを用いる場合、フィールド名のダッシュをアンダースコアとし、値となる情報は必ずURLエンコードしてください。
例:user[field_name]

URIでパラメーターを用いたPOSTリクエストのAPIコールサンプルです。
選択ください
POST /api/users/567fk.json?account=&password=secret&user[name]=user@example.com&user[password]=secret&user[full_name]=Full%20Name

上記の例では、認証としてMD5ハッシュのチェックサムを用いています。
パスワードの直接表記はセキュリティ的に問題があるため、MD5ハッシュを用いた暗号化を強く推奨します。

ユーザーを指定して情報の取得

選択ください
GET /api/users/{id}.json
指定されたユーザーIDが全て数値である場合、SuperSaaSユーザーIDであるとしてユーザー特定の処理されます。
それ以外である場合は登録時に用いられたユーザーIDとして、ユーザー特定の処理が行われます。
もしユーザーIDがアルファベットの文字列の場合、ネームフィールドに保存されます。
文字列である場合はURLエンコードされます。
該当ユーザーがある場合、ステータスコード200 (OK)が返り、ユーザー情報がレスポンスされます。
該当ユーザーが見つからない場合は、ステータスコード404 (Not Found)が返ります。
<user>
   ...
</user>
{
  "id": "123456",
  "name": "example",
  "email": "example@gmail.com",
  ...
}

全てのユーザー情報を取得

GET /api/users.json
ステータスコード200 (OK)が返り、ユーザー情報がレスポンスされます。
ユーザー情報の取得は、100件を通常の最大取得数としています。
/api/users?limit=500のようにlimitパラメーターで最大数を指定することができます。
1000件を超えるなど長大な場合など、/api/users.json?limit=1000&offset=1000として、offsetパラメーターを活用した分割取得も可能です。
<users>
   <user>
      ...
   </user>
   <user>
      ...
   </user>
</users>
[
  {
    "id": "123456",
    "name": "example",
    "email": "example@gmail.com",
    ...
  },
  {
    "id": "789123",
    "name": "example2",
    "email": "example2@gmail.com",
    ...
  }
]

ユーザー情報に紐づくフォーム情報

フォームがユーザーに関連付けられている場合は、パラメーターに form = true を追加してフォームのデータを取得できます。
フォームAPIも合わせて参照ください。

ユーザー情報の更新

ユーザー情報の更新はHTTP PUTリクエストで/api/usersAPIをコールします。
ユーザーの作成と同様に、XML、JSON形式でURLエンコードされたURIパラメーターを使用します。

選択ください
PUT /api/users/{id}.json

指定されたユーザーIDで特定されるユーザー情報が更新されます。
成功した場合、ステータスコード200 (OK)が返ります。
失敗した場合は、ステータスコード422 (Unprocessable Entity)が返り、エラーがレスポンスされます。

もし、該当するユーザー情報が見つからない場合、APIは新規登録を試みます。
自動的に新しいレコードを作成しないためには、パラメーターにnotfound=errorもしくはnotfound=ignoreを追加します。
それぞれ、ステータスコード404 (Not Found)200 (OK)が返ります。

ユーザーIDにSuperSaaSユーザーIDを用いられている場合、該当ユーザーが見つからない時には常にステータスコード404 (Not Found)が返ります。

HTTP PUTリクエストが利用できない場合、POSTリクエストで代行することも可能です。

ユーザー情報の削除

ユーザー情報の削除はHTTP DELETEリクエストで/api/usersAPIをコールします。

選択ください
DELETE /api/users/{id}

指定されたユーザーIDに該当するユーザー情報を削除します。
成功した場合、ステータスコード200 (OK)が返ります。
該当ユーザーが存在しないなど、失敗した場合はステータスコード404 (Not Found)が返り、エラーがレスポンスされます。

HTTP DELETEリクエストが利用できない場合、_method=DELETEをパラメーターに追加することでPOSTリクエストで代行することが可能です。

トラブルシューティング

  • もしメールアドレスが不正などメールアドレスバリデーションエラーの場合、アカウントの設定を確認ください。
  • もしユーザーのリダイレクトに成功してもログインができない場合、クッキー情報が失われている可能性があります。
    これはAPIにアクセスする際に使用しているドメインとユーザーを送信するスケジュールのドメインが異なる場合に発生します。
    ドメインはどちらも同じである必要があります。
  • ログインせずにスケジュールにアクセスできる場合、不特定多数への開示は推奨されません。
    万が一、不正な利用が発生しても、そのクライアントを特定できない可能性がありますので、必ず特定できるユーザーのみ利用できる仕組みとすることを推奨します。
    特定できないユーザーには、通常の使い方でのアクセスか、あるいは、別の同等スケジュールの開示で代替願います。
  • もしBad request – unknown attribute: field-1のようにリクエストエラーの場合、パラメーター名に注目ください。
    XMLの場合、パラメーター名のハイフンをアンダースコアにします。
    コール方法でuser[field_1]<field-1>となります。