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

Question

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

我已经进行了大量研究以寻找最佳实践等，并确定了我认为将提供相当灵活的响应通信系统的内容。

我的问题是:

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

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

API说明:

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

我希望这是通过 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 header 下发送)；

<?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 key 。该 API key 链接到系统中的用户，然后允许内部方法执行为该特定用户启用的一组有限功能。

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

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

Answer 1

肖恩，

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

我的回答只有在这个假设成立时才适用——我并不是要批评您的设计，而只是批评它的 RESTfulness。

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

我会尝试通过下面的简短回答让您入门，但请查看 http://nordsc.com/ext/classification_of_http_based_apis.html我在这里更多地讨论这个问题。然后，您可以将所有这些分解为更小的问题，然后返回此处或访问 Yahoo 组上的休息讨论:http://tech.groups.yahoo.com/group/rest-discuss/

现在对您的设计进行简短评论:

1. 您不应使用自己的响应代码，而应仅使用 HTTP 提供的响应代码。您可以自行编写，但这些必须普遍适用，而不是特定于您的应用程序或交互。

2. 您应该使用特定的媒体类型，而不仅仅是 application/xml。如果现有类型都不符合您的需要(或可以扩展以满足您的需要)，您可以开发自己的类型。事实上，主要的设计事件应该花在媒体类型上。这是您的领域语义所在。

3. 您必须遵守超媒体约束才能成为真正的 RESTful。这意味着应向客户提供链接和/或表格，以发现下一步可以做什么。

使用上面引用的分类，你的 API 看起来像一个基于 HTTP 的类型 I ( http://nordsc.com/ext/classification_of_http_based_apis.html#http-type-one ) 假设你没有在你的 URI 中放置操作，这将使其成为 RPC URI -隧道 ( http://nordsc.com/ext/classification_of_http_based_apis.html#uri-rpc )

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

一月