API原則
このセクションでは、市場をリードするAPIを作成するために当社が準拠する標準の概要を説明します。
API設計アプローチ
当社は使い慣れたツールをご利用いただくために、業界標準の規則に従っています。当社のモジュラーAPIは特定の使用例でご利用いただけます。尚、モジュラーAPIは支払の流れを最適化するように設計されています。 また、当社のAPIはセルフサービスを可能にするように設計されています。APIは貴社に次の手順を示し、簡単に学習でき、そして貴社の統合をサポートする文書と認定を提示します。
APIはどのように機能しますか?
貴社のシステムと簡単に統合できるように、アクションをRestful HTTPリソースとして提示しています
まず、ルートリソースを取得して、利用可能なものを表示することから始めます。 当社は、標準化されたHTTP方法(POST、PUT、GETなど)を実行できるリソースを提供しています。
貴社の処理を最適化するための動的なアクションリンク
当社のAPIサービスを利用して、特定の決済処理に合わせて次のアクションを最適化できます。
動的なアクションリンクをハイパーメディアリンクとして返し、決済処理を直感的で学習が簡単のものにし、また貴社が間違いを犯すことを防ぎます。
注記:動的な次のアクションリンクは、個々の取引タイプに固有のものです。ベースURLを除く暗号化アクションリンクデータの最大長は最大1024文字です。
以下の例は、
ルートリソースに照会を実行したとき に返される_links
オブジェクトです。これらのリンクを使用すると、支払を承認したり、トークンを作成したりできます。Copied!{ "_links": { "payments:authorize": { "href": "https://try.access.worldpay.com/payments/authorizations" }, "tokens:tokens": { "href": "https://try.access.worldpay.com/tokens" } } }
{ "_links": { "payments:authorize": { "href": "https://try.access.worldpay.com/payments/authorizations" }, "tokens:tokens": { "href": "https://try.access.worldpay.com/tokens" } } }様々な使用例をサポートするモジュラーリソースと複合リソース
一部のアクションリンクは動的であり、最適な支払の流れをガイドします。当社のAPIは、支払パターンと結果を最適化できるように、APIを貴社の処理システムに統合できるツールセットとして設計されています。 尚、次のアクションリンクの一部は複合であり、1回の呼び出しで複数のアクションを実行できます。
様々なインタラクティブな処理間で一貫した言語
当社はAPIの統合と使用の簡易化に重点を置いており、様々なサービスで同じ言語を使用することを目指しています。尚、同じ言語を使うことで、学習しやすく、使いやすい、迅速な統合を保証することができるのです。
学習性のためのハイパーテキストアプリケーション言語(HAL)
HALは、APIリソースとリンクの形式を定義します。HALは、APIリソース間のハイパーリンクを一貫させ、簡単にします。またHALを利用することで、様々なAPIを相互リンクして、より消費可能で探索可能なエクスペリエンスを提供することができます。
HALは、機械と人間の両方が判読でき、API参考文献からコンテキストを取得できます。
標準ライブラリで使用できるように、この規則に従って、リソースとアクションのリンクを構造化しています。
APIバージョンの使用を制御するメディアタイプ
メディアタイプは、JSONファイルの性質と形式を指定します。ファイルの処理方法を定義します。リクエストの形式は標準を満たしていなければなりません。尚、満たさない場合、リクエストは受け入れられません。
メディアタイプは
Content-Type
ヘッダーで定義され、APIバージョンを定義し、API全体で標準化されています。Copied!Content-Type: application/vnd.worldpay.payments-v6+json
Content-Type: application/vnd.worldpay.payments-v6+json
ベストプラクティス
Access Worldpayは、サービス応答のヘッダーでWP-CorrelationId
を返します。これをログに記録することを強くお勧めします。各サービスリクエストを確認するためにWP-CorrelationId
を使用します。
バージョン管理
上記の例は、
APIを更新すると、以前のスキーマが最新の更新でサポートされなくなる可能性があります。文書は常に最新バージョンのAPIを反映していますが、以前のバージョンのスキーマを見つけるには、
以前のAPIの文書は、
なぜ新しいAPIバージョンをリリースするのですか?
APIに新機能を導入するため。破壊的変更が発生する可能性があります。
新しいAPIバージョンは常に破壊的変更を導入しますか?
通常はそうです。以前のバージョンのAPIでは認識できない新たなパラメーターをリクエストに導入することがあります。
バージョンには下位互換性がありますか?
いいえ、各バージョンは異なるスキーマを受け入れる場合があります。
破壊的変更の定義
Access API(アクセスAPI)に統合する際の復元力を保証するには、Worldpayが別のバージョンに移行せずに次の変更を行う可能性があることを考慮しなければなりません。
応答で:
URIの構造と長さ、完全修飾ドメイン名(FQDN)とそのパスを含むURIは変更される可能性があります。
例:
{
"_links": {
"service:action": {
"href": "https://access.worldpay.com/service/action"
},
{ "_links": { "service:action": { "href": "https://access.worldpay.com/service/action" },
または
{
"_links": {
"service:action": {
"href": "https://api.access.worldpay.com/api/process"
},
{ "_links": { "service:action": { "href": "https://api.access.worldpay.com/api/process" },
応答本文内の要素は、任意の順序で送信できます。
例:
{
"apple": "gala",
"pear": "conference"
}
{ "apple": "gala", "pear": "conference" }
または
{
"pear": "conference",
"apple": "gala"
}
{ "pear": "conference", "apple": "gala" }
新しいオブジェクトまたはオブジェクト内の新しい属性が応答に含まれるようになりました。
例:
前
{
"apple": "gala",
"pear": "conference"
}
{ "apple": "gala", "pear": "conference" }
後
{
"apple": "gala",
"pear": "conference",
"melon": "honeydew"
}
{ "apple": "gala", "pear": "conference", "melon": "honeydew" }
追加のアクションリンクとURIリソースが応答内に返されるようになりました。
例:
前
{
"_links": {
"service:action1": {
"href": "https://access.worldpay.com/service/action1"
},
"service:action2": {
"href": "https://access.worldpay.com/service/action2"
}
}
}
{ "_links": { "service:action1": { "href": "https://access.worldpay.com/service/action1" }, "service:action2": { "href": "https://access.worldpay.com/service/action2" } } }
後
{
"_links": {
"service:action1": {
"href": "https://access.worldpay.com/service/action1"
},
"service:action2": {
"href": "https://access.worldpay.com/service/action2"
},
"service:action3": {
"href": "https://access.worldpay.com/service/action3"
}
}
}
{ "_links": { "service:action1": { "href": "https://access.worldpay.com/service/action1" }, "service:action2": { "href": "https://access.worldpay.com/service/action2" }, "service:action3": { "href": "https://access.worldpay.com/service/action3" } } }
新しい機能が新しいエラー状態を保証する場合、追加の
新しいHTTPヘッダーが応答に追加されました。
リクエストで
重要:文書に記録されていない要素を送信すると、エラーが返されます。
リクエスト本文内の要素は、任意の順序で送信できます。
例:
{
"apple": "gala",
"pear": "conference"
}
{ "apple": "gala", "pear": "conference" }
または
{
"pear": "conference",
"apple": "gala"
}
{ "pear": "conference", "apple": "gala" }
必須ではない新しい要素を送信できるようになりました。例えば、Payments API(支払API)のmerchant.mcc
やTokens API(トークンAPI)のdescription
などです。
例:
前
{
"apple": "gala",
"pear": "conference"
}
{ "apple": "gala", "pear": "conference" }
後
{
"apple": "gala",
"pear": "conference",
"melon": "honeydew"
}
{ "apple": "gala", "pear": "conference", "melon": "honeydew" }
要素の値により、文字数を増やすことができるようになりました。
例:
前
{
"phrase": "the quick brown fox"
}
{ "phrase": "the quick brown fox" }
後
{
"phrase": "the quick brown fox jumps over the lazy dog"
}
{ "phrase": "the quick brown fox jumps over the lazy dog" }
例:
以前は時間と分しか許可されていなかった"時間"値が、オプションで秒も許可するようになりました。
前
{
"time": "11:50"
}
{ "time": "11:50" }
後
{
"time": "11:50:59"
}
{ "time": "11:50:59" }
受け入れる値の範囲を拡大する場合があります。以前は確認エラーが発生したリクエストが成功する可能性があることを意味します。
例えば、以前に許可された範囲値は10~50でした。新しい範囲は10~100です。
要素値のオプションが増えました。
例:
以前に許可された値オプションはapple
、pear
およびmelon
です。今は、mango
を送信することもできます。
前
{
"fruit": "apple"
}
{ "fruit": "apple" }
後
{
"fruit": "mango"
}
{ "fruit": "mango" }
注記:上記の定義以外の変更については、Worldpayは新しいバージョンを作成します。現在の標準については、