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

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

我做了大量的研究，寻找最佳实践，并确定了我认为可以提供相当灵活的响应通信系统的方法

我的问题是：

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

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

API说明：

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

我希望这是通过SSL连接通过CURL请求实现的

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

请求完成
速率限制状态响应
40
31

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

1201
API错误
请求的API版本（1.5）无效

此外，我正在设置可搜索文档中使用的错误代码，以减轻其他开发人员的痛苦。请求的通过/失败将通过适当的HTTP代码给出——成功（200）、错误请求（400）、未找到方法（404）、身份验证失败（403）等

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

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

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

我遵循API的“黄金法则”——“总是添加，从不删除”

所以。。我还应该考虑什么？我错过了什么？

XML看起来不错。

---

但是，要想更多地了解内部逻辑，我们需要的不仅仅是XML的细节。

作为示例，您可以使用的最佳API是您编码的API。使用相同的命名约定和大小写

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

以下几点：

1） 将响应头放在不同的位置—HTTP头和响应_代码—肯定会导致混淆。有些开发人员会在一个地方检查它，有些会在另一个地方检查。如果要使用该路由，请绝对确保HTTP头和返回的XML之间的响应代码相同

2） 服务器不必在每次响应时都返回API版本。你在电线上浪费时间。如果客户机需要特定版本的API，请让他们在请求中发送它。你不必把它还给他们

---

3） 将响应\u代码和请求\u状态结合起来。看看HTTP是如何做到的：200-299意味着成功。400-499表示客户端是哑的。500-599表示服务器坏了

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

如果你提出了一个计划，先弃用旧版本，然后再删除旧版本，这应该不会太痛苦。

Shane

我假设您的目标是构建一个RESTful API——这是真的吗

我的回答只有在这个假设成立的情况下才适用——我不是在批评你的设计，只是批评它的宁静

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

我将试着从下面的简短回答开始，但请看一下我在哪里更多地讨论这个问题。然后，您可能可以将所有这些问题分解为更小的问题，然后回到这里或访问雅虎群组上的rest讨论：

现在，对您的设计发表简短评论：

您不应该使用自己的响应代码，而应该只使用HTTP提供的响应代码。您可以编写自己的，但这些必须是通用的，而不是特定于您的应用程序或交互

您应该使用特定的媒体类型，而不仅仅是application/xml。如果现有的类型都不符合您的需要（或者可以进行扩展），您可以开发自己的类型。事实上，主要的设计活动应该花在媒体类型上。它是您的域语义所在的位置

您必须遵守超媒体约束才能真正做到宁静。这意味着应该向客户机提供链接和/或表单，以发现它下一步可以做什么

使用上面提到的分类，如果您不在URI中放置操作，那么您的API看起来像是一个基于HTTP的类型I（），这将使它成为RPC URI隧道（）

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

---

JAN < /P> > P>如果您真的在构建REST服务，请考虑这一点：

• request\u status

  ，应该改为html响应代码（至少200:正常，400:错误请求，401:未授权，403:禁止和500:内部错误），

  response\u code

  可能需要在您的文档中找到问题的解释
• 如果希望提供不同的格式，则响应的格式不应取决于url，而应取决于

关于您的“单一URL/端点”想法-请记住，使用Apache，您可以为潜在的unl提供服务

<?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 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>

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