首页 / 知识

关于api设计：如何构建良好的(网络)API

2023-04-13 13:55:00

我将为网络应用程序构建API，我对人们可以建议的良好做法感兴趣。

我已经在计划对其进行版本控制(版本1只能控制系统的某些方面，版本2可以控制更多功能，但这可能需要更改身份验证的执行方式，而该方式与版本1不兼容)，并且身份验证将不同于人们用于登录的标准用户名/密码(如果有人确实使用了恶意工具，则无论api允许什么，它都不会对其进行完全模拟)。

是否有人有进一步的想法，或者您使用过具有特别好的API的网站示例？

阅读RESTful Web服务一书，该书为您提供了有关如何在实践中使用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的优势和语义来实现预期的功能。就像网络本身一样，它是面向资源的。

Amazon Web Services，Google和许多其他公司提供REST API来与其产品进行交互。

使用REST。

阅读API标准，或复制其中一种流行的想法。

验证用户时要小心。

开始非常非常简单。

建立一个使用您的API(即使它没有用)来检查一切是否正常的网站。也许您可以构建该网站的移动版本，或者强迫您深入使用该API。