Question

我正处于规划和早期编码阶段，为我们的大规模应用编写我的第一个完整的API。多年来我使用了几个API，但这是我第一次被要求构建一些允许在这个级别上进行编程交互的东西。

我已经做了很多研究，寻找最佳实践等，并确定了我认为将提供相当灵活的响应通信系统。

我的问题是：

这是您期望看到的API交互吗？

我错过了什么重要的事吗？

API的解释：

我将使用HTTP Type 1协议进行通信，并使用唯一的API密钥进行身份验证。

我希望通过SSL连接来通过CURL请求。

成功（200 OK）XML响应（速率限制请求）的示例：

<?xml version="1.0" encoding="UTF-8"?>
<node>
    <short_message>Request Complete</short_message>
    <long_message>Rate Limit Status Response</long_message>
    <response_data>
        <rate_limit>40</rate_limit>
        <rate_used>31</rate_used>
    </response_data>
</node>

XML响应失败的示例（将在适当的400/500标头下发送）;

<?xml version="1.0" encoding="UTF-8"?>
<node>
    <error_code>1201</error_code>
    <short_message>API Error</short_message>
    <long_message>The requested API version (1.5) is invalid</long_message> 
</node>

此外，我正在设置可在搜索文档中使用的错误代码，以缓解其他开发人员的偏头痛。请求的通过/失败将通过适当的HTTP代码给出 - 成功（200），错误请求（400），未找到方法（404），认证失败（403）等......

我也在使用基于版本的端点，因此任何代码更改都不需要更改外部代码。

最后，开发人员将能够以XML，JSON或PHP序列化数组请求所有响应。

我的代码内部非常简单。所有数据都通过POST（可能使用CURL或其他替代方法）传递，包括唯一的API密钥。该API密钥链接到系统中的用户，然后允许内部方法执行为该特定用户启用的一组有限的功能。

我遵循API'黄金法则' - “始终添加，永不删除”。

那么......我还应该考虑什么以及我错过了什么？

Answer 1

沙恩，

我假设您的目标是构建RESTful API - 这是真的吗？

我的回答只有在这个假设成立的情况下才适用 - 我不是要批评你的设计，只是它的RESTfulness。

REST定义了4个接口约束，您的设计必须遵守这些约束才能成为RESTful。您的设计至少违反了其中的三个，因此不是RESTful。这本身并不一定是坏事，但重要的是要了解您的系统可能没有您期望的属性。

我会尝试让您开始下面的简短回答，但请查看http://nordsc.com/ext/classification_of_http_based_apis.html我在哪里讨论这个问题。然后，您可以将所有这些分解为较小的问题并回到此处或访问雅虎小组的休息讨论：http://tech.groups.yahoo.com/group/rest-discuss/

现在简短评论你的设计：

您不应该使用自己的响应代码，而只使用HTTP提供的代码。您可以自己制作，但这些必须是普遍适用的，而不是特定于您的应用或互动。
您应该使用特定的媒体类型，而不仅仅是application / xml。如果现有类型都不符合您的需求（或者可以扩展到这样做），您可以开发自己的类型。实际上，主要的设计活动应该花在媒体类型上。这是您的域语义所在。
您必须遵守超媒体约束才能真正成为RESTful。这意味着应该为客户提供链接和/或表格，以发现它可以做什么。

使用上面引用的分类，您似乎是一个基于HTTP的Type I （http://nordsc.com/ext/classification_of_http_based_apis.html#http-type-one），假设您没有在URI中添加操作，这会使其 RPC URI-Tunneling （http://nordsc.com/ext/classification_of_http_based_apis.html#uri-rpc）

我希望这可以帮助您实现总体目标。

扬

Answer 2

一些事情：

1）将响应标头放入不同的位置 - HTTP标头和response_code - 肯定会引起混淆。一些开发人员会在一个地方检查它，一些在另一个地方。如果您想使用该路由，请确保HTTP标头和返回的XML之间的响应代码相同。

2）您的服务器不必返回每个响应的API版本。你在线上浪费了一些东西。如果客户端需要特定版本的API，请让他们在请求中发送它。您无需将其发回给他们。

3）结合response_code和request_status。看看HTTP是如何做到的：200-299意味着成功。 400-499意味着客户是愚蠢的。 500-599表示服务器已拧紧。

Answer 3

如果您真的在构建REST服务，请考虑以下事项：

request_status，应该支持html响应代码（至少200：OK，400：Bad Request，401：Unauthorized，403：Forbidden and 500：Internal Error），response_code需要在文档中找到问题的解释。
您希望提供不同的格式，响应的格式不应取决于网址，而应取决于Accept header

Answer 4

XML看起来不错。但是要更多地谈论内在逻辑，我们需要更多的细节，而不仅仅是XML。

Answer 5

您可以使用的最佳API是您编码的API。使用相同的命名约定和套管。

此外，尝试使用您的API构建示例应用程序，您将很快发现它的缺点。

Answer 6

您是否考虑过使用版本化端点？他们可能需要您进行更多的规划和维护，但是每次您决定更改参数/返回值时，您的用户都不必重写代码。

如果你想出一个弃用然后删除旧版本的计划，这不应该太痛苦。

Answer 7

关于您“单个URL /端点”的想法 - 请记住，使用Apache，您可以通过URL重写规则从单个脚本提供可能无限数量的URL。这意味着通过在“端点”脚本的目录中正确定义的.htaccess文件，您可以让您的Web服务器自动“映射”这样的传入请求，例如：

/foo/slice/1234 => /foo/?action=slice&oid=1234
/foo/dice/3456  => /foo/?action=dice&oid=3456
/foo/chop/4567  => /foo/?action=chop&oid=4567

如果您决定要提供“RESTful”URL（并且可以使用HTTP请求模式GET，POST，PUT，DELETE，HEAD），这将非常有用。

构建自定义API - 需要逻辑检查

7 个答案: