我应该如何构建一个好的(Web)API

我将为一个Web应用程序构建一个API,我对人们可以建议的良好实践感兴趣.

我已经计划将其版本化(版本1只能控制系统的某些方面,版本2可以控制更多,但这可能需要更改执行与版本1不兼容的身份验证的方式),以及身份验证将与人们用于登录的标准用户名/密码不同(如果有人使用恶意工具,则无论api允许的话,都不会打开它们进行完全模拟).

有没有人有更多的想法,或者您使用过特别好的API的网站示例？

阅读RESTful Web Services一书,它可以让您对实践中如何使用REST有一个很好的概述,并且能够快速地加速以便立即开始,并且有信心.这比仅查看现有API更有用,因为它还讨论了设计选择和权衡.

1)将版本号直接烘焙到URL中,而不是将其作为参数传递,因为这使您可以完全自由地更改每个版本凹凸的API命名空间的组织.

2)保持URL重写规则(如果有的话)尽可能简单/精简(但不是更简单),同时使您的URL尽可能美观(但不能更多).

3)始终寻找可以为每个响应找到的最佳HTTP状态代码(例如,不要忘记202和207).

4)实现法西斯参数验证逻辑和信息性错误消息.

5)在适当的地方使用HTTP请求头而不是参数(例如,Accept,允许客户端指定响应的所需数据格式).

6)组织你的"名词",使得不同客户受众使用的URL在URL树的"根"附近分开(这样,如果需要,可以更容易为不同的受众强制执行不同的身份验证机制,甚至可以映射URL树的不同部分到不同的服务器).

7)如果您在与API相同的域中提供常规网页并使用相同的身份验证凭据,则需要在API请求中使用X-Requested-With标头,以避免XSRF漏洞.

我会看一下经过验证的API:

YouTube API

Twitter API

关于这些API是否"好"有很多争论,但我认为它们的成功得到了证明,而且它们都很容易使用.

使用REST.

RESTful Web服务体系结构易于实现,并使用HTTP的优势和语义来实现它们的目的.它是面向资源的,就像网络本身一样.

亚马逊网络服务,谷歌和许多其他公司提供REST API来与他们的产品进行交互.