转载

开发人员怎么才能让开放API易于使用和理解？

决定使用哪一个API标准很重要，因为每一API标准的目标人群都很特别。如果你想支持大量的用户，那么就使用一个简单的API，这并不需要多大的开销，如RESTful API。REST标准非常广泛。最好的做法是确保你的API是一致的。例如，我没有使用SOAP，因为它过于复杂。

SOAP是构建基于Web 的API的主要协议，但与之REST和JSON相比，它过于陈旧。我发现，让JSON取代SOAP和XML来做为响应可以使生活变得更简单。JSON让我返回一个简单的对象格式，它几乎可以以任何语言解析。

为了认证（如OpenID，OAuth和SAML），给常见的API附上标准可以让你的API容易为开发人员和非开发人员所使用。如果你不为用户处理认证问题，就要使用简单的基于HTTP的或基于令牌的身份验证来取代OpenID、OAuth或SAML，他们设计的主要目的是作为用户进行身份验证。

另外，提供一个自身已经存档的开放API对于开发人员是有益的。我最近开始在我的API中添加Swagger API文档。Swagger允许开发人员为API自动产生代码，这些代码可以多语言的。如果你没有遵循这一方法，你至少要确保你提供了API客户库使用是最流行的语言，如Java、Node.js、Python、Ruby和面向对象C（它是用于开发移动应用的）。

关键是要遵循简单的软件信条和标准。不要重新创造API，不要把认证复杂化。

正文到此结束