开发人员在考虑最终用户的情况下创建软件

这是软件开发的本质。开发人员在考虑最终用户的情况下创建软件。看起来很简单，但有时这些用户也是开发人员。他们不需要为他们分解的东西。他们甚至不需要简单。他们想要的就是访问 - 一种将软件与他们的软件集成的方法。这是API(应用程序编程接口)的用武之地。在本文中，我希望强调您可以采取的五个步骤来创建成功的API。

谈到软件开发，我们都不想重新发明轮子。此时，几乎所有大型Web公司都有其软件产品的API。研究这些API并尝试了解创建它们的不同设计决策。

有许多不同的技术，但您将看到的大多数API将使用RESTful接口或SOAP。如果你想要使用哪个API接口，我建议使用HTTP协议进行RESTful方法。它比SOAP更简单，它目前更受欢迎，并且在使用基于Web的软件产品时更容易上手。

始终如一

开发人员最欣赏的一点是一致性。除其他外，这包括可寻址性，输入参数，输出格式和错误处理。

使用RESTful方法时，有许多不同的URI命名方案。每个人都有它的支持者，所以只需选择一个并坚持下去。输入和输出结构也是如此。大多数API支持使用XML和JSON作为输入和输出格式。我建议支持两者，但选择默认格式。

对于输入，您的输入要求应该一致地命名，并且应该在您正在进行的API调用的上下文中有意义。对于输出，请确保使用通用数据结构布局。如果要将一个API调用的输出包装在 XML标记中，请考虑使用其他调用执行此操作。

通常的做法是在发送回客户端的输出数据中包含某种状态标志。使用RESTful API方法时，应使用HTTP状态代码完成此操作。例如，如果您刚刚在现有数据对象上处理了PUT请求，则响应中包含的HTTP状态代码将根据请求的结果而有所不同。

可以使用标准的“200 OK”状态代码来表示请求是成功的，而不是指示呼叫状态的任意标志，而可以使用“400 Bad Request”状态代码来表示请求是畸形。有很多HTTP状态代码可以在不同的情况下使用。

使用OAuth

大多数软件产品都涉及某种用户身份验证，以便为该用户访问受保护的资源。对于API，让客户端收集用户凭据以发送到您的服务器是一种不好的做法。这就是OAuth的用武之地

.OAuth提供了许多优于第三方用户名/密码身份验证的优势。最重要的是，客户端永远无法访问用户的凭据。用户在登录时会被重定向到您的服务器。用户登录到您的站点后，他或她将被重定向回客户端，客户端将在该客户端接收访问令牌，以便在将来对受保护资源的请求中使用。

使用OAuth的另一个重要好处是用户可以随时取消客户端访问。如果用户因任何原因决定不再希望客户端能够代表他们访问受保护资源，他们只需转到您创建的接口并取消客户端的访问权限。

尽早开始

使API成功的最重要的事情之一就是尽早开始。当您编写该函数以在数据库中创建一些条目时，请继续并花费额外的时间并为其编写API接口。

写好文档

没有比没有好的文档更快地杀死API。虽然一些开发人员可以采用记录不良的API并弄清楚它应该如何工作，但大多数人都不愿意。

您应该记录您可用的每个API调用，并根据它们所处理的数据类型对API调用进行分类。除了记录API调用本身的端点外，还应系统地定义必需和可选的输入参数以及输出数据结构。输入参数应列出默认值(如果有)，并指示预期的数据格式，如数字或字符串。最后，每个API调用都应该有一个错误条件和状态代码列表。

要完善您的文档，请确保为每个API调用包含一个或两个示例，以了解常见的输入和输出方案。

API开发：保持简单

尽管开发API似乎是一项复杂的工作，但API本身的概念并不是一个新概念，而且我们在此处讨论的每个主题都有大量可用的文档。只需确保在可以找到它们的地方使用良好实践，并提供一致且记录良好的界面。