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

我正处于规划和早期编码阶段,为大规模的应用程序编写我的第一个完整的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’黄金法则’ – “永远添加,永不删除”.

那么……我还应该考虑什么,我错过了什么？

解决方法:

巴蒂尔,

我假设你的目标是构建一个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)

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

一月

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

相关文章