php - 像Web门户那样的ebay之类的API接口(interface)

Question

我们已经开发了用于Graphics Job Work的B2B Web门户，它类似于Camera Ready Art（www.camerareadyart.com）。它适用于希望将位图转换为矢量图形，徽标设计以及将黑白图像着色为彩色等常规图像处理的人们。

我们希望添加功能，以便人们（我们的客户）可以使用我们提供的一组API从他们的网站直接发布他们的工作，而不必访问我们的网站来发布他们的工作。

到目前为止，我从未做过这样的事情，所以我对如何实现这样的事情一无所知。我还想知道我们如何实现安全性，以便只有获得授权的人员才能发布其工作？

谁能给我关于我们如何做这样的事情的想法。

Answer 1

这个问题涉及的范围很大，我怀疑任何一个答案都不能涵盖所有细节。我能做的是根据我犯的错误提供一些起点。

建立在您自己的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获取数据或将数据发布到其中一个URL时，会发生什么情况？如何处理错误，如何处理异常？回复采取什么形式？

我不能告诉你在这里做什么。就我个人而言，我更喜欢将事物尽可能地映射到HTTP，然后仅在需要时才进行扩展。

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

使用HTTP的现有方面
除了明智地使用HTTP状态代码外，在滚动自己的解决方案之前，请确保四处寻找仅HTTP方法来执行操作。

希望用户指定响应格式是XML还是JSON？使用HTTP Accept标头。

是否想将客户端重定向到其他URL来获取请求结果？使用HTTP Location标头。

HTTP有许多功能已经可以处理许多您想做的事情。使用它们！

安全
这里要解决两个普遍问题：验证用户身份，以及确定给定用户可以执行的操作。

安全性：认证
用户将需要在他们的请求中指定他们是谁。

想到的第一个解决方案是允许用户指定用户名和密码，该名称和密码可能与他们用来访问您的应用程序的用户名和密码相同。从表面上看，这似乎是一个好主意，但并不理想。

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

更好的选择是让用户提供身份验证令牌，该令牌本质上是用户唯一的单个值，就像用户名和密码合并为一个一样。

这使您可以在逻辑上将用户名和密码与对API的访问分开。用户可以在不中断对API的访问权限的情况下，随时更改自己的用户名和/或密码。

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

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

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

如果您明智地选择了一组URL，其中每个URL都会执行一个唯一的操作，那么此过程将为您提供最好的访问控制级别。

为了提供更好的控制级别，您可能还希望针对允许令牌访问的每个URL指定允许使用哪些查询参数。