UI とシームレスに統合
API は、データソースをUIコンポーネントにシームレスに統合するプロセスを容易にするように設計されており、APIリクエストの状態をUIの状態に自動的に結び付けます。
たとえば、input
にAPIビヘイビアを追加するとoninput
で発生し、button
の場合はonclick
でサーバーにクエリを実行します。
テンプレート化されたURLの保持
APIは、コードからURLを分離するのに役立ちます。コード内で`http://foo.com/get/1.0/followers.json`のようなURLの代わりに、`get followers`のような名前付きAPIアクションを使用します。
コードベース全体でURLを変更する必要がないように、すべてのAPIを一元的に管理します。直感的なテンプレートシステムを使用してエンドポイントを定義し、UIにあるデータを自動的に渡します。
HTTP 200は成功ではありません
コールバックが実行される前に、JSONで`success`条件を解析し、サーバーエラーが正しくキャッチされ、フロントエンドコードでエラー条件がトリガーされるようにします。
APIの動的翻訳
扱いにくいコードを使用するサードパーティのAPIを使用していますか?問題ありません!APIを使用すると、コードで消費される前にAPIの生のJSON応答を変更できます。
サードパーティ統合とモックのためのツール
response
やresponseAsync
などの新しい強力なコールバックを使用すると、非同期的に応答をモックし、APIと同じコールバックをトリガーできます。
APIの例

APIの作成
APIアクション
APIは、インターフェース要素がクエリできるサーバーアクションのセットを定義することで機能します。アクションは通常、`save profile`や`get followers`のような短いフレーズで表され、サーバー上のテンプレート化されたURLリソースに対応します。
アクションで指定されたURL変数は実行時に置換されるため、個々のコンポーネントは異なるURLをクエリできます。
APIにリストされているURLには、必須パラメーターとオプションパラメーターを含めることができ、各呼び出しごとに調整できます。
必須パラメーター
オプションパラメーター
APIの作成
エンドポイントはアプリケーションで一度だけ定義する必要があります。通常、これは各ページに含まれる中央の構成ファイルで行われます。
これらの名前付きAPIエンドポイントは、グローバルに$.fn.api.settings.api
に格納されます。
エンドポイントを一箇所に定義することで、アプリケーションを更新する際に、新しいURLで単一の位置のみを更新するだけで済みます。
URLの使用
名前付きAPIアクションはAPIを使用するのに必須ではありません。手動でリクエストのURLを指定し、同じテンプレートを使用することもできます。
APIアクションのクエリ
APIイベントの添付
APIイベントは、ページ上の要素に名前付きアクションを添付することでトリガーされます。これらのアクションはAPIで名前付きエンドポイントを検索し、各呼び出しに対して要素からのテンプレート化された値を変換します。
任意の要素にAPIアクションを直接添付できます。デフォルトでは、アクションは要素の種類に最も適したイベントで発生します。たとえば、ボタンはサーバーをonclick
で呼び出し、入力欄はoninput
で呼び出し、フォームはonsubmit
で呼び出します。
APIアクションとデータは、初期化時にJavaScriptで指定できます。
APIアクションとデータは、メタデータで指定することもできます。
DOMイベントの指定
APIイベントが発生するアクションをオーバーライドする必要がある場合は、on
パラメーターを使用できます。
即時呼び出し
APIアクションをすぐに実行する必要がある場合は、on: 'now'
を使用します。これにより、呼び出された要素への同じ状態更新はトリガーされますが、すぐに実行されます。
新しい設定オブジェクトを渡すと、以前のインスタンスとそのすべての設定とイベントが破棄されることに注意してください。以前のインスタンスを保持する場合は、query
ビヘイビアを使用して新しいリクエストをトリガーできます。
リクエストの設定
データのURLへのルーティング
API URLにテンプレート化された変数が含まれている場合、継承の順序で示されている4つの方法のいずれかで、リクエスト中に置換されます。
URLで使用されるすべてのパラメーターは、デフォルトでencodeURIComponent
を使用してエンコードされ、悪意のある文字列がクエリに影響を与えるのを防ぎます。この機能を無効にするには、encodeParameters: false
を設定できます。
1. 自動ルーティングされるURL変数
URLアクションで指定されている場合、いくつかの特別な値は自動的に置換されます。
変数 | 説明 | 使用可能 |
---|---|---|
テキスト | 要素の現在のテキスト値 | すべての要素 |
値 | 要素の現在の入力値 | 入力要素 |
2. データ属性で指定されたURL変数
URL値をHTML5メタデータ属性として含めることができます。
これは、トリガー要素ごとに固有のURLデータを含める最も簡単な方法です。たとえば、多くのフォローボタンは同じエンドポイントをトリガーしますが、それぞれに独自のユーザーIDがあります。
3. Javascriptで指定された設定
URL変数とGET/POSTデータは、Javascriptオブジェクトで実行時に指定できます。
4. beforeSendから返された設定
URLデータだけでなく、すべてのランタイム設定は、APIリクエストの送信前に発生する特別なコールバック`beforeSend`で調整できます。
リクエストの調整
XHRの変更
追加のコールバック`beforeXHR`を使用すると、リクエストを送信する前にXHRオブジェクトを変更できます。これは、リクエストを送信する前にヘッダーを変更するなど、XHRリクエストのプロパティを調整する場合に役立ちます。
リクエストの無効化
便宜上、APIは現在無効になっている要素からのリクエストを自動的に防止します。
リクエストのキャンセル
beforeSendを使用して、リクエストを行うための特別な条件を確認することもできます。`beforeSend`コールバックがfalseを返す場合、リクエストはキャンセルされます。
データの受け渡し
1. ルーティングされたフォームデータ
`serializeForm`設定を使用するか、フォームにAPIイベントをアタッチすると、APIはサーバーに送信されるデータに最も近いフォームを自動的に含めます。
構造化されたフォームデータは、いくつかの理由からjQueryのserializeよりも有益です。
- Serialize Objectは、`name="name[first]"`のような構造化されたフォーム名をネストされたオブジェクトリテラルに正しく変換します。
- 構造化されたフォームデータは、Javascriptの`beforeSend`で変更できます。
- フォームデータは自動的にJavascriptの同等物に変換されます。たとえば、チェックボックスは`boolean`値に変換されます。
構造化データの例
次のフォームは、上記で述べた構造化されたフォームデータの利点の一部を示しています。
2. Javascriptでルーティングされたデータ
サーバーデータは、APIリクエストを初期化するときに直接指定できます。
3. beforeSendに追加されたデータ
POSTまたはGETデータは、特別なコールバック`beforeSend`を使用して指定できます。これは、リクエストを送信する前にデータを取得するために使用できます。
サーバー応答
応答コールバック
サーバーからの正常な応答は`onSuccess`をトリガーし、無効な結果は`onFailure`をトリガーします。
`onError`は、XHRエラーの場合にのみトリガーされますが、無効なJSON応答の場合はトリガーされません。
`onResponse`コールバックを使用して、成功テストに対して解析される前にJSON応答を調整できます。
JSONの成功の判定
APIには、JSON応答に対する特別な成功条件があります。リクエストのHTTP応答に基づいて成功と失敗のコールバックを提供する代わりに、サーバーの応答がアクションが成功したことを示している場合のみ、リクエストは成功したと見なされます。応答は検証テスト`successTest`に渡され、これを使用してJSONの有効な応答を確認できます。
たとえば、すべての成功したJSON応答は、応答の成功を示す最上位のプロパティを返すことが期待される場合があります。
この`success`値を確認する成功テストを指定できます。これは、ほとんどの場合、すべてのAPIリクエストに対してグローバルに設定されます。
応答JSONの変更
バージョン2.0以降、APIには`onResponse`コールバックが含まれています。これにより、応答が検証される前にサーバーの応答を調整できます。これにより、他のコールバックが起動する前に応答を変換できます。これは、API応答を変更できないが、応答が必要なJSON構造に準拠する必要がある状況に役立ちます。
状態の制御
UI状態
APIは、`loading`と`error`のクラス名を自動的に追加します。これにより、API呼び出しの進行に合わせて異なるUI状態を自動的にトリガーできます。
トリガーAPI要素とは異なる要素に状態クラス名を受け取らせる必要がある場合は、`settings.stateContext`を使用して異なるセレクターを指定できます。
`stateContext`を使用すると、送信ボタンを押したときにフォームに読み込み状態をトリガーするなど、簡単に操作できます。
APIモジュールに含まれる状態
状態 | 説明 | APIイベント |
---|---|---|
loading | ユーザーが待つ必要があることを示します | XHRが初期化されました |
error | エラーが発生したことを示します | XHRリクエストがエラーを返します(ページの変更によって発生したonAbort、またはsuccessTestが失敗した場合はトリガーされません)。`settings.errorDuration`の間表示されたままになります。 |
disabled | APIアクションを防止します | none |
テキスト状態
状態モジュールを使用してAPIアクションを初期化すると、アクティブ化または非アクティブ化状態の設定や、各状態のテキスト値の調整など、UI状態をより詳細に制御できます。
状態モジュールに含まれる状態
状態 | 説明 | 発生時 |
---|---|---|
inactive | デフォルトの状態 | |
active | 選択された状態 | 成功したAPIリクエストで切り替えられます |
activate | アクティブ化アクションを説明します | 非アクティブの場合にホバー時 |
deactivate | 非アクティブ化アクションを説明します | アクティブの場合にホバー時 |
hover | インタラクションを説明します | すべての状態でのホバー時に、activate/deactivateを上書きします |
disabled | 要素を操作できないことを示します | プログラムでトリガーされます。APIリクエストをブロックします。 |
flash | 一時的なメッセージを表示するために使用されるテキストのみの状態 | プログラムでトリガーされます |
success | ユーザーアクションが成功したことを示します | プログラムでトリガーされます |
warning | ユーザーアクションに問題があったことを示します | プログラムでトリガーされます |
高度な使用方法
応答の実行
バージョン2.0以降、APIには新しいパラメーター`response`と`responseAsync`が2つ含まれており、Javascriptオブジェクトまたは関数を指定してAPI応答を返すことができます。(これらは以前は`mockResponse`と`mockResponseAsync`でした。)
カスタムバックエンドの使用
`responseAsync`を使用すると、APIリクエストを実行できる関数を指定できます。これにより、APIリクエストの統合のために`$.ajax`の外部でカスタムバックエンドまたはラッパーを使用できます。
動作
次のすべての動作は、次の構文を使用して呼び出すことができます。
動作 | 説明 |
---|---|
query | 既存のAPI設定を使用してクエリを実行します |
urlデータの追加(url, data) | 既存のテンプレート化されたurlにデータを追加し、完全なurl文字列を返します |
get request | 現在のAPIリクエストのプロミスを取得します |
abort | 現在のAPIリクエストを中断します |
reset | 要素からloadingとerrorの状態を削除します |
was cancelled | 最後のリクエストがキャンセルされたかどうかを返します |
was failure | 最後のリクエストが失敗したかどうかを返します |
was successful | 最後のリクエストが成功したかどうかを返します |
was complete | 直前のリクエストが完了したかどうかを返します。 |
無効化されています。 | 要素が無効化されているかどうかを返します。 |
モック化されています。 | 要素のレスポンスがモック化されているかどうかを返します。 |
読み込み中です。 | 要素が読み込み中かどうかを返します。 |
読み込み状態を設定します。 | 要素に読み込み状態を設定します。 |
エラー状態を設定します。 | 要素にエラー状態を設定します。 |
読み込み状態を削除します。 | 要素から読み込み状態を削除します。 |
エラー状態を削除します。 | 要素からエラー状態を削除します。 |
イベントを取得します。 | APIリクエストが発生するイベントを取得します。 |
URLエンコードされた値(value)を取得します。 | 渡された値が既にエンコードされていない場合のみ、encodeURIComponent 値を返します。 |
キャッシュされたレスポンスを読み込みます(url) | URLに対してローカルにキャッシュされたレスポンスを読み込みます。 |
キャッシュされたレスポンスを書き込みます(url, response) | URLに対してキャッシュされたレスポンスを書き込みます。 |
キャッシュを作成します。 | 新しいキャッシュを作成し、ローカルにキャッシュされたすべてのURLを削除します。 |
破棄します。 | ページとすべてのイベントからAPI設定を削除します。 |
API
AJAX
API
デフォルト | 説明 | |
---|---|---|
オン | 自動 | APIイベントが発生するタイミング |
キャッシュ | true | JSON APIを使用する際に、成功したAJAXレスポンスをキャッシュするために「local」に設定できます。これにより、APIエンドポイントが繰り返しアクセスされた場合に同じ結果を返す場合、サーバーへのラウンドトリップを回避できます。false に設定すると、URLにキャッシュバストパラメータが追加されます。 |
状態コンテキスト | this | UI状態はこの要素に適用されます。デフォルトでは、トリガー要素になります。 |
パラメータのエンコード | true | URL文字列に追加する前に、encodeURIComponent を使用してパラメータをエンコードするかどうか |
デフォルトデータ | true | {value}や{text}などのデフォルトデータを自動的に含めるかどうか |
フォームのシリアライズ | false | 最も近いフォームをシリアライズしてリクエストに含めるかどうか |
スロットリング | 0 | リクエストが行われた後にリクエストをトリガーするまでの待機時間。oninput のレート制限に役立ちます。 |
初回リクエストのスロットリング | true | falseに設定すると、他のリクエストがキューイングされていない場合、最初のリクエストは遅延されません。 |
リクエストの中断 | false | 別のリクエストが保留中の間にもAPIリクエストを実行できるかどうか |
読み込み表示時間 | 0 | 読み込みインジケーターを表示する最小時間 |
エラーの非表示 | 自動 | デフォルトのauto は、要素がform でない限り、エラー発生後、エラー表示時間を経過するとエラー状態を自動的に削除します。 |
エラー表示時間 | 2000 | true に設定すると、エラーは削除されません。ミリ秒単位の時間(duration)を設定すると、リクエストエラー後にエラー状態を表示する時間になります。 |
リクエスト設定
デフォルト | 説明 | 可能な値 | |
---|---|---|---|
アクション | false | クエリ用の名前付きAPIアクション。元々は$.fn.settings.apiで指定されています。 | 文字列またはfalse |
URL | false | クエリ用のテンプレート化されたURL。指定されたアクションを上書きします。 | 文字列またはfalse |
URLデータ | false | 置換に使用する変数 | |
レスポンス | false | サーバーからJSONをリクエストする代わりに、自動的に返されるJavaScriptオブジェクトに設定できます。 | {}またはfalse |
responseAsync(settings, callback) | false | 指定されている場合、この関数はサーバーからコンテンツを取得し、標準的なAJAX呼び出しの代わりに非同期で返すために使用できます。コールバック関数はサーバーレスポンスを返す必要があります。 | 関数またはfalse |
mockResponse | false | response のエイリアス |
|
mockResponseAsync | false | responseAsync のエイリアス |
|
メソッド | get | サーバーにリクエストを送信するメソッド | 有効なHTTPメソッド |
データ型 | JSON | レスポンスの予想されるデータ型 | xml, json, jsonp, script, html, text |
データ | {} | リクエストに送信するPOST/GETデータ |
コールバック
コンテキスト | 説明 | |
---|---|---|
beforeSend(settings) | 初期化された要素 | リクエストの前に設定を変更したり、リクエストをキャンセルしたりできます。 |
beforeXHR(xhrObject) | リクエストのXHRオブジェクトを変更できます。 | |
onRequest(promise, xhr) | 状態コンテキスト | リクエストが行われたときに発生するコールバック。API成功PromiseとXHRリクエストPromiseの両方を取得します。 |
onResponse(response) | 状態コンテキスト | APIイベントの成功を判断するために他のコールバックによって解析される前に、サーバーのレスポンスを変更できます。 |
successTest(response) | 完了したJSONレスポンスを成功として扱うかどうかを決定します | |
onSuccess(response, element, xhr) | 状態コンテキスト | 成功したレスポンス後のコールバック。JSONレスポンスはsuccessTest を通過する必要があります。 |
onComplete(response, element, xhr) | 状態コンテキスト | 条件に関係なく、リクエスト完了時のコールバック |
onFailure(response, element) | 状態コンテキスト | 失敗したレスポンス、またはsuccessTest に失敗したJSONレスポンス時のコールバック |
onError(errorMessage, element, xhr) | 状態コンテキスト | 返されたステータスコードからのサーバーエラー、またはXHRエラー時のコールバック。 |
onAbort(errorMessage, element, xhr) | 状態コンテキスト | ユーザーがリンクをクリックしたり、リクエストを手動でキャンセルしたりすることによって発生した中断時のコールバック。 |
モジュール
これらの設定はすべてのモジュールにネイティブであり、コンポーネントがコンテンツをDOM属性にどのように結び付けるか、およびモジュールのデバッグ設定を定義します。
デフォルト | 説明 | |
---|---|---|
名前 | API | ログステートメントで使用される名前 |
名前空間 | api | イベントの名前空間。モジュールのティアダウンが、要素にアタッチされた他のイベントに影響を与えないようにします。 |
正規表現 |
regExp : { required: /\{\$*[A-z0-9]+\}/g, optional: /\{\/\$*[A-z0-9]+\}/g, }
|
テンプレートマッチングに使用される正規表現 |
セレクタ |
selector: { disabled : '.disabled', form : 'form' }
|
モジュールの部分を検索するために使用されるセレクタ |
クラス名 |
className: { loading : 'loading', error : 'error' }
|
要素の状態を決定するために使用されるクラス名 |
メタデータ |
metadata: { action : 'action', url : 'url' }
|
XHRとレスポンスPromiseを格納するために使用されるメタデータ |
サイレント | False | 他のデバッグ設定に関係なく、エラーメッセージを含むすべてのコンソール出力を無効にします。 |
デバッグ | false | コンソールへのデバッグ出力 |
パフォーマンス | true | パフォーマンスメトリクスを含むconsole.table 出力を表示します。 |
詳細 | false | デバッグ出力には、すべての内部動作が含まれます。 |
エラー |
// errors error : { beforeSend : 'The before send function has aborted the request', error : 'There was an error with your request', exitConditions : 'API Request Aborted. Exit conditions met', JSONParse : 'JSON could not be parsed during error handling', legacyParameters : 'You are using legacy API success callback names', missingAction : 'API action used but no url was defined', missingSerialize : 'Required dependency jquery-serialize-object missing, using basic serialize', missingURL : 'No URL specified for API event', noReturnedValue : 'The beforeSend callback must return a settings object, beforeSend ignored.', parseError : 'There was an error parsing your request', requiredParameter : 'Missing a required URL parameter: ', statusMessage : 'Server gave an error: ', timeout : 'Your request timed out' }
|