用于门户网站的类似易趣的API界面

这个问题涉及的范围很广,我怀疑任何一个答案都能详细地涵盖问题。我能做的是根据我犯的错误提供一些起点。

基于您自己的API构建
不要将API功能添加到现有系统中。这样做会:

• 导致额外的测试负载(您必须独立测试应用程序和API)
• 导致整体维护成本增加
• 导致API质量比您想要提供的要差

您的总体目标应该是首先构建API,然后在自己的API之上构建应用程序。这样做有以下好处:

• 在测试应用程序时,API的测试是固有的。
• 您不会“忘记”添加任何必需的API方法

你的应用程序和你的应用程序逻辑(API)在逻辑上是分开的——在等式的每一边做什么和它负责什么的问题上,它们之间会有一个清晰的分开。这将有助于指导发展。这也可以让你很容易地把应用程序和API放在不同的机器上,在需要的时候。

使用自己的API是非常重要的一点。您的API的设计最初将是次优的,只有通过您自己使用它,您才能使它以一种高效的方式向人们提供实际需要的功能。

您最终将得到一个大致如下的系统:

-------------                          -------------
|           |                          |           |
| Your APP  | <= HTTP communication => | Your API  |
|           |                          |           |
-------------                          -------------

这突出了一些进一步的好处:您可以用任何其他应用程序替换“您的应用程序”,允许您的客户创建应用程序,以最适合他们的方式处理事情。您还可以在现有API的基础上创建应用程序的新版本-移动到公共网站的新版本可能会更容易。

设计URL:映射到类和方法
选择合理的URL和选择合理的类和方法名称一样是一个问题。从类及其方法派生URL是一种很好的方法。如果在URL和类/方法之间没有合理的关联,从长远来看,您会发现很难维护这些内容。

我个人更喜欢通过以下方式将URL与类和方法相关联:

• 将类映射到顶级目录
• 将方法映射到顶级目录的子目录

例子:
您的API的URL是 https://api.camerareadyart.com .
你有一个 image 对象与 toColour() 和 toBlackAndWhite() 方法。

这可能映射到:

https://api.camerareadyart.com/image/toColour/
https://api.camerareadyart.com/image/toBlackAndWhite/

与位图到矢量转换类似:

https://api.camerareadyart.com/bitmap/toVector/

设计响应
当有人从某个URL获取数据或向其发布数据时,会发生什么?如何处理错误,如何处理异常?回答采取什么形式?

我不能告诉你在这里做什么。就我个人而言,我更喜欢尽可能地将事物映射到HTTP,然后只在需要时超出这个范围。

例如,如果一个传入请求被接受并被处理,但在内部遇到错误,我将发出一个500状态响应。同样,如果给定的API方法需要尚未提供的身份验证,我可能会发出403。利用现有的HTTP特性可以防止您不得不重新发明某些东西。

使用HTTP的现有方面
除了明智地使用HTTP状态代码之外,在滚动您自己的解决方案之前,一定要寻找一种只使用HTTP的方法来做一些事情。

希望用户指定响应格式是XML还是JSON?使用HTTP接受头。

要将客户端重新定向到其他URL以获取请求的结果吗?使用HTTP位置头。

HTTP有许多特性已经处理了许多您可能想做的事情。使用它们!

安全性
这里有两个要解决的一般问题:验证用户身份,以及确定给定用户可以执行哪些操作。

安全:身份验证
用户需要在他们的请求中指定他们是谁。

首先要想到的解决方案是允许用户指定用户名和密码,可能与他们访问应用程序时使用的用户名和密码相同。表面上这似乎是个好主意,但并不理想。

用户最终会将他们的用户名和密码烘焙到他们自己的应用程序中。不可避免的是,一个用户会忘记他们的密码,并将其更改,以便他们可以愉快地访问您的应用程序,在这个过程中破坏了他们自己的应用程序。

一个更好的选择是用户提供一个身份验证令牌,它本质上是用户唯一的一个值,就像用户名和密码一样。

这允许您在逻辑上将用户名和密码与对API的访问分开。用户可以根据自己的喜好随时更改应用程序的用户名和/或密码,而不必破坏对API的访问。

用户还可以拥有多个API令牌,每个令牌具有不同的访问级别,从而允许用户安全地将API令牌分发给第三方服务。

安全:访问控制
就外部世界而言,您的API是一组URL。根据定义,每个URL都是唯一的,并执行唯一的任务。基于这些概念建立访问控制机制是一个很好的起点。

我更喜欢为每个令牌保留一个允许令牌访问的URL列表。当一个给定的令牌被用来访问一个URL时,很容易知道哪个URL正在被访问,以及它是否在令牌允许的URL列表中。

如果您明智地选择一组URL,其中每个URL执行一个唯一的操作,那么这个过程将为您提供您将要获得的访问控制的最佳级别。

为了提供更精细的控制级别,您可能还需要为每个允许令牌访问的URL指定允许它们使用的查询参数。

显然,您需要设计并运行后端Web服务。但是,所有附加功能(安全性、限制、OAuth密钥管理、订户门户、尝试API的交互式控制台等)都是一组相当标准的功能,您可能不应该自己开发这些功能。

市场上有商业API管理解决方案。我为wso2工作,它有一个100%开源(Apache许可证)的wso2 api管理器,您可以免费下载。 here 或用作云托管版本 WSO2 API Cloud .