API 原则

本节将概述我们创建市场领先的 API 时所遵循的标准。

API 设计方法

我们遵循行业标准规则，这样您就可以使用熟悉的工具。我们的模块化 API 可以帮助您处理具体用例。这两方面相结合旨在优化您的支付流程。 我们的 API 旨在让您实现自助服务。它们为您展示了后续步骤是可学习的，并提供文档和认证以支持您的集成。

它如何工作？

• 将操作作为 Restful HTTP 资源呈现，便于集成到您的历程之中

  第一步是获取根资源，以便向您展示可用的资源。 我们提供了可供您按其执行标准化的 HTTP 方法（POST、PUT、GET 等）的资源。

• 用于优化您的历程的动态后续操作链接

  我们的 API 服务可以优化您特定支付历程的后续操作。

  我们将动态后续操作链接作为超媒体链接返回，以便使可能的支付历程变得直观且可学习，同时避免您犯错误。

  注释：我们的动态化下一操作链接对于单笔交易的操作类型是独一无二的。加密操作链接数据（不包括基础 URL）的最大长度将达到 1024 个字符。

  以下示例显示了在您查询根资源时返回的 _links 对象。这些链接可让您授权支付或创建 Token。

  Copy

  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 易于集成和使用，因此在不同服务中的语言都旨在保持一致。这可确保可学习性、可用性和快速集成。

• 用于可学习性的超文本应用语言 (HAL)

  HAL 定义了 API 资源和链接的格式。它让 API 资源之间的超链接保持一致和便捷。它可让您将我们不同的 API 链接起来，从而获得更易于使用和探索的体验。

  HAL 是机器和人类均可读的语言；这是一种意味着您可以从 API Reference 中获取上下文的优势。

  我们遵循这个规则来构造资源和操作链接，以便您利用标准库来使用它们。

• 控制 API 版本使用的 Media Types（媒体类型）

  Media Type 规定了 JSON 文件的性质和格式。它定义了处理文件应采用的方式。请求的格式必须符合标准，否则请求就不会被接受。

  我们的 Media type 在 Content-Type 头文件中定义，它指明了 API 版本并在整个 API 中实现了标准化。

  Copy

  Copied!

  Content-Type: application/vnd.worldpay.payments-v6+json

  Content-Type: application/vnd.worldpay.payments-v6+json

最佳实践

Access Worldpay 在服务响应的头文件中返回WP-CorrelationId。我们强烈建议您将此记录下来。我们使用WP-CorrelationId检查单个服务请求。

版本控制

上述示例显示我们的Payments API目前为版本 6。我们致力于更新 API，以便为您提供最新的功能。您可以在各自 API 文档底部查阅任何中断或非中断更改和发布日期。比如，我们的 Payments API 的版本控制/更改日志保存在此处。

更新 API 可能意味着在最新的更新不再支持以前的架构。我们的文档总是反映了 API 的最新版本，但若要查找以前版本的架构，请参见我们的API 参考。

您可以在旧版本一节中查阅以前 API 的文档。

您为什么发布新的 API 版本？

在我们的 API 中引入新功能，这样可能会引入一个中断更改。

新版 API 总是会引入中断更改吗？

一般而言是这样的，我们可能在请求中引入以前版本 API 无法识别的新参数。

各版本是否后向兼容？

不兼容，每个版本都可能接受不同的架构，我们在API 参考中详细描述了每个版本的架构，因为文档主要反映了 API 的最新版本。

非中断更改定义

为确保在集成到我们任何 Access API 中时的弹性，您必须考虑到 Worldpay 可能会迁移到另一个版本的情况下做出以下更改：

在响应中：

{
    "apple": "gala",
    "pear": "conference"
}

{
    "pear": "conference",
    "apple": "gala"
}

{
    "apple": "gala",
    "pear": "conference"
}

{
    "apple": "gala",
    "pear": "conference",
    "melon": "honeydew"
}

{
    "_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"
        }
    }
}

在请求中

{
    "apple": "gala",
    "pear": "conference"
}

{
    "pear": "conference",
    "apple": "gala"
}

{
    "apple": "gala",
    "pear": "conference"
}

{
    "apple": "gala",
    "pear": "conference",
    "melon": "honeydew"
}

{
    "phrase": "the quick brown fox"
}

{
    "phrase": "the quick brown fox jumps over the lazy dog"
}

{
    "time": "11:50"
}

{
    "time": "11:50:59"
}

{
    "fruit": "apple"
}

{
    "fruit": "mango"
}

您现在应该已经熟悉我们在证书处理方面的最佳实践。