ドキュメンテーション
印刷ページ

ユーザーAPI

もしあなたのサイトがログインシステムとデータベースを持っている場合
このAPIでSuperSaaSのデータベースと同期する事が可能です。
この事によりあなたのユーザーが登録とログインを一回で行う事が可能です。

APIを使用することでSuper SaaSデータベースを常に最新の状態にしていくために、
いくつかのオプションが以下にあります。
最も簡単な方法はシングルボタンにあります。:

  1. サイト上に現時点でサイトにログインしている人のすべての関連情報を含むBook Nowのボタンを作ります。
  2. そのボタンをクリックするとSuperSaaSの APIに情報が表示されるとともに、他者の書き込みを阻止する確認作業が行われます。
  3. 初めてご利用の場合は入力された情報をもとに新しいユーザーアカウントが作成され、SuperSaaSに送信されます。
    初めてのご利用でない場合は現存する情報が必要に応じて更新されます。
  4. 利用者は次回ご利用の際には自動でログインすることができます。

この作業方法は、初期のフルシンクのせずに、頻繁にSuperSaaSを利用しているあなたのユーザーのサブセットだけに
シンクすることができます。
理論的には、もしあなたがボタンを実装した場合のみ、データベースがシンク外に飛び出す、小さなリスクがあります。
これは、もしユーザーの情報を、あなたのサイト上で変更し、そのままボタンをクリックせずにSuperSaaSに戻った場合に起こります。
例えば、それは、そのページにブックマークをつけたからです。
もし、これが、あなたがサーバーサイドを実装する問題ならば、APIが下記の詳細を呼び出し、あなたのサーバーから更新された情報を、
ユーザー情報があなたのサイト上で変更される毎に、直接SuperSaaSに送ります。
APIコールは、既存しないユーザーに関して、不作動する可能性が多少あります。
ですから、SuperSaaSのアクティブユーザーのサブセットのみで維持していただけます。

上記の方法と違う方法としましては、あなたのユーザーデータベースの初期シンクをすることです(手入力、又は、自動的)、
あなた自身のデーターベースを更新する毎に、あなたのサーバーからAPIコールに送られ、SuperSaaSをシンク状態に維持します。
その後、自動的にそれらをログインできる、単純なリンクを作成して、あなたのスケジュールにリダイレクトできます。

SuperSaaSの変更に伴い、あなた自身のデーターベースを作成することが出来ます。
しかし、話し合いの後、あなたはSuperSaaSをリードし、従わせるデーターベースを作成したいと理解しています。
従って、あなたは、人々が、SuperSaaSデータベース内で、彼らの情報を変更することを避けたいのなら、以下の設定を作成してください。:

  • アクセスコントロールページ内"誰がログイン名を作成出来ますか?"で"あなたのサイト上でログインと登録を管理"を選択して下さい。
  • あなたのサイトでemailアドレスをログイン名として使用してない場合"e-mailアドレスをログイン名として使用する"のチェックを外して下さい。
  • "どんな情報をユーザーが入力すべきですか..."では適切なフィールドを選択して下さい。 "パスワード"をオフにする事が可能です。
  • こちらのオプションのチェックも必要でしょう。"ユーザー自身による情報の更新を防ぐ"これによりあなたのデータベースが主導のままです。
  • レイアウト設定ページ上で、”あなたのURL"が記入されていることを確認します。あなたのサイトに、最初、ログイン無しで訪れた人たちが、そこに送られます。

ログインの作成

シングルサインオンを実装する為の、最も簡単な方法は、あなたのサイトから、ユーザーを送るとき、
必要なすべての情報を提供する事です。
SuperSaaSが、既存するユーザーかどうかを確認し、必要に応じて、データベースのレコードを更新、作成します。

これを作動する為に、あなたのサイト上に設置する例示HTMLスニペットです。:
<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モジュール、Drupalモジュール、又はWordPressプラグインをダウンロードできます。Joomla moduleDrupal moduleWordPress plugin

データベース・キーの3つのオプション

双方のデータベースの変更の記録をつける為に、同じユニーク・キーを使用する必要があります。
このIDは、変更が必要なレコードを特定する為の各トランザクションと一緒に送られる必要があります。
簡単な実装の手助けの為に、3つの選択肢があります。:

  1. あなただけのユニークな32ビット数を提供します。
    一般的に、あなた自身のユーザーデータベースのインデックス・キーが適しています。
    あなたが、あなた自身のキーを示していることを、あなたのIDに”fk”(外部キー)のレターを添えてポストしてください。
  2. 内部SuperSaaSユーザーID(こちらも32ビット数です)を使用することが出来ます。
    あなたが新しいレコードを作成した時に、そのIDを取り出し、あなた自身のデーターベース内に収納しなくてはなりません。
    その後、それは、あなたがレコードを更新する時に一緒に送られます。
  3. あなたは、人の名前をキーとして使用できます。数字で始まらない、ユニークな50バイト文字列です。
    もし、この価値を変えてしまう可能性のある文字をキーとして利用するのは、あまりお勧めできません。
    それを変えるたびに、ブッキングから切断されてしまうかもしれないからです。
    もし、あなたのデーターべスキーが、32バイト数以外の何かであるのなら、よく考えてキーを登録してください。

MD5ハッシュ・チェックサムを利用した認証

APIは、いくつかの違うタイプの認証をサポートします。
サーバーからサーバー通信に対しては、URLパラメーターとして、あなたのアカウント名とパスワードを送るか、HTTP基本認識ヘッダー、SSLによって接続を保護する選択もあります。
しかしながら、当然のことですが、上記のスニペットのようなHTMLにあなたのアカウントパスワードを入力してはいけません。
そのページにアクセスした人に、あなたのパスワードを明かしてしまうことになります。

HTMLの認識の為には、パスワードを送らずにリクエストし、いくつかのフィールドのワンウェイMD5ハッシュを計算し、リクエストに追加します。
そのハッシュは、あなたのアカウント名、ユーザー名、あなたのアカウントパスワード(ユーザーパスワードではありません)を含む、連結した文字列から、割り出されます。
それは、あなた自身とSuperSaaSしか知らないアカウントパスワードを含んでいるので、他の誰にも割り出すことは出来ません。
チェックサムは、訪問者名を含むので、各訪問者によって、違います。
ブラウザーによって実行される為に、安全に、それを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'}")

フォームは、すでに、チェックサムで認証されているので、ユーザーパスワードを提供する必要はありません。
ユーザーパスワードを送ることは出来ますが、避けたほうが良いでしょう。
何故なら、ウェブページ上で、見られる可能性があります。
もし、レコードが正常に作成、又は更新された場合、ユーザーは、”後(after)”バラメーターを含むURLにリダイレクトされます。
あなたは、ユーザーが、あらかじめ決められた日付と表示に行くことを、確実にする為に、このURLに追加項目を提供できます。
また統合チュートリアルに説明されているように、予約欄用のあらかじめ入力された項目を含むことも出来ます。統合のチュートリアル.

もし、あなたがサインオンボタンを提供し、そこで終わるのであれば、シンクを抜け出せる二つのデータベースがあります。
もしかしたら、受け付けれらない恐れもありますが。
例えば、誰かが、彼の情報を、あなたのサイト上で変え、ひょっとすると、彼は彼のブラウザー歴を利用し、その後、リンクを通らずに、彼はSuperSaaSへ戻るかもしれません。
また、あなたがあなた自身のデータベースから削除したユーザーは、SuperSaaSデータベースから削除することは出来ません。
これを避ける為に、あなたのサーバー上で、ユーザー情報を変更する毎に、APIコールに以下の詳細を送ることによって、あなた自身のサーバーからSuperSaaSデータベースを更新することができます。

単純ログイン (API作成なし)

あなたが、手入力、又は下記のAPIコールにて、すでにデータベースをシンクさせられた場合、
上記のコールと同じパラメーターを利用し、下記のリンク(POST、又は、GET)にてユーザーをログインできます。
http://www.supersaas.com/api/login?account=Your_acount_name&after=Schedule_url&user[name]=user@client.com&checksum=A4E67...DFEF

ユーザーAPI

ユーザーデータベースのAPIはRESTfulです。
Ruby on Rails の ActiveResource のように、適切に書き込まれたライブラリーによって、利用可能です。
各コールには、URLのパラメーターとしてあなたのアカウントとパスワードを追加するか、ベーシックHTTP認証を利用して確認する必要があります。
例として:http://supersaas.com/api/users?account=YourName&password=secret.です。
また上記で述べたMD5チェックサムを利用する事もできます。
さらにセキュリティーのために、SSLを使うことも出来ます。

新規ユーザーの作成

リクエストには、新しいユーザーと示すXMLドキュメント、もしくはエンコードしたURIパラメーターを含めるべきです。
フォーマットについてはドキュメントの最後をご覧ください。

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が含まれています。
e.g.: Location: http://www.supersaas.com/api/users/1234.xml
あなたが作成したオブジェクトのSuperSaaS ID(1234)を知りたい場合は、このURLからそれを抽出することができます。

作られたオブジェクトのSuperSaaS ID (1234)を見つけたいのであれば、このURLから見つけ出すことができます。
オブジェクトがバリデーションをパスしなかったのであれば、おそらく電子メールアドレスが正しくないためで、エラーメッセージを含むステータス422 ("Unprocessable Entity")が返されます。

もしすでにあなた自身のキーを提供していて、そのキーがすでにデータベースにあるのでしたら、
あなたのコールが代わりに更新されるはずです。
自動的に作られたり、更新と解釈されるのを防ぐには、 パラメーター"duplicate=raise"を追加します。
そうすれば、ステータスコード422が代わりに帰ってきます。注意が必要です。
あなたのブッキングIDがピリオドを含んでいる場合は、それを正しく動作させるためには "/api/users?id={id}" としてそれを呼び出す必要があります。

データのフォーマット

あなたが送るフィールドは、Accessコントロールのスクリーンで設定できます。
ユーザーネームを除き、すべての値を選択でき、特になければ、デフォルトの値(通常はブランク)に設定されます。

FieldComment
nameRequiredユーザーネームは、最大50バイトです。もしあなたがメールアドレスをログインネームとして選択したならば、これがメールアドレスになるはずです。
emailOptionalユーザーのemailアドレス。もしemailアドレスをログイン名として使用している場合は無視
passwordOptionalユーザーのパスワード。 もしパスワードをログイン時に使用している場合
full-name, address, mobile, phoneOptionalこれらの属性のいずれかが存在する場合、それらはUTF-8でエンコードされた文字列として変更されずに保存されます。
countryOptional存在しないか2文字のISO 3166-1国名コードのどちらかISO 3166-1 country code
field-1, field-2,
super-field
Optional2つのカスタムフィールドおよびスーパーバイザフィールドの値、ユーザー・インタフェースに与える表示ラベルとは無関係。
creditOptionalクレジットレベルの設定 (デフォルトは 0)。支払い設定上で選択されたフォーマット。
roleOptionalAllowed values are:
3: Regular user (default)
4: Superuser
-1: Blocked user

データを読み取る際に取得したXMLドキュメントは、上記のものに加え、次のフィールドが含まれます。
FieldComment
idSuperSaaSによりこのユーザーに割り当てられた内部ID
fk外部キーを指定した場合あなたによってこのユーザに割り当てられたID
created-onUTCで作成されたこのユーザー時間

使用例

XMLを使用するコールのこの例は、SuperSaaSユーザーデータベース内に新しいユーザレコードを作成します。
レコードには、あなた自身のデータベース内のデータベースキー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>

これにより、 空文の201 Createdレスポンスが返信されます。
もしあなたがクエリーパラメータを使用する場合、フィールドレーベル内のダッシュをアンダースコアに入れ替え、
user[field_name]として入力してください。
値は、URIエンコードをしてください。

以下は先と同じ模範コールですが、今回はクエリーパラメータを使用する場合です。:
POST /api/users/567fk?account=demo&password=secret&user[name]=user@example.com&user[password]=secret&user[full_name]=Full%20Name

単一ユーザー情報の読み込み

GET /api/users/{id}
そのIDが全部数字であるなら、それは我々のキーと思われます。
そうでないなら、あなたのキーと考えられます。
もしそのIDがアルファベットでしたら、それはネームフィールドに保存されます。
アルファベットのIDは、URLの不正キャラクターを防止するためにURIエンコードされたパラメーターとして送られます。
例:/api/users?id=ab%25cd ユーザーを示すXMLドキュメントのレスポンスボディーと一緒に404 Not Foundもしくは(200 OKのレスポンスがあります。
<user>
   ...
</user>

全てのユーザー情報の読み込み

GET /api/users
これは、あなたのアカウントのすべてのユーザーを示すXMLドキュメントと合わせて200 OKを戻します。
あなたが/api/users?limit=500のようなリミットパラメーターを追加しない限り、記録数は100に限られます。
<users>
   <user>
      ...
   </user>
   <user>
      ...
   </user>
</users>

ユーザー情報の更新

ユーザーをアップデートするにはHTTP PUT requestを/api/usersへ送信する必要があります。

PUT /api/users/{id}

システムは任意のID レコードを探し更新します。
”作る”のAPIと同様に、XMLドキュメントあるいはURIエンコードされたパレメーターを送ると、
結果は200 OKもしくはエラードキュメント付きの422 Unprocessable Entityとなります。

レコードが見つからない場合は、システムはあなたが作りたいのだと勘違いしてしまいます。
自動的に新しいレコードを作るのを防ぐには、パラメーターとしてnotfound=errorもしくはnotfound=ignoreを追加します。

存在しないSuperSaaS内部キーを使用としているのでしたら、404 Not foundが常に返されます。

あなたが使用しているソフトウエアがHTTP PUT Verbを送るのをサポートしていないならば、単に通常のPOSTを代わりに返します。

ユーザー情報の削除

ユーザーを削除はIDを指定して、HTTPでDELETEリクエスト/api/usersを送信することによって行うことができます。

DELETE /api/users/{id}

システムはデータベースにあるそのIDを探し、レコードを問題なく削除したならば200 OKを、
あるいは、すでに存在してないならば404 Not foundを返します。

あなたが使用しているソフトウエアが、HTTP DELETE Verbを送れないならば、
追加のパラメーターとして_method=DELETEを付けたPOSTをしなければなりません。

トラブルシューティング

  • もし"Emailが有効ではありません"が表示された場合はSettingsを見返して再度確認して下さい。
  • もしボタンがユーザーをリダイレクトしたのに、そのユーザーをログイン許可しなかった場合、
    クッキーが途中で紛失したことになります。
    最も一般的な原因は、あなたがAPIにアクセスする際に使用しているドメインと、
    あなたがユーザーを送信するスケジュールのドメインが異なるためです。これらは同一でなければなりません。
  • ログインせずに人々にアクセスさせる場合、SuperSaaSへのオートマティックログインが出来ない事を確認したいでしょう。
    匿名ユーザー向けに有効ログイン情報は生成出来ないでしょうが、もし出来た場合、
    匿名ユーザーは他者の予定を閲覧、変更可能となります。
    もし、ログインせずに匿名ユーザーがスケジュールを閲覧出来るようにしたいなら、
    かわりに彼らに通常のリンクを提供する事も可能でしょう。
  • "Bad request - unknown attribute: field-1"というエラーが出たら、貴方はPOSTにアンダースコアではなく名前にダッシュを使ったのでしょう。以下を使用すべきでしょう。user[field_1] in REST calls and <field-1> in XML calls.