如何设计Web服务API？方法？工具？输出？

Question

我是网络应用程序设计的新手。当代Web应用程序通常采用这种形式：

• 前端利用各种JS框架构建UI。
• 然后前端使用JS调用后端Web服务来交换XML或JSON数据并相应地更新UI。
• 后端分为多个层，并将Web服务API公开给任何外部。
• 后端层之间的通信也存在Web服务API。

因此，Web服务API应该是设计的关键部分。

我们如何设计它？具体来说：

• 启动设计需要哪些数据/材料？
• 我们可以使用哪些工具？ （我听说过将XML转换为类的一些工具。）
• 设计的最终输出是什么样的？

ADD 1

具体来说，假设有这样的要求：

  

  

1. 客户应该可以上传和删除某些文件   文件存储库。

  

2. 在修改文件存储库中的文件之前，必须对客户进行身份验证。

  

如何将其转换为详细的API规范，然后具体的类定义？

相关链接：http://piwik.org/blog/2008/01/how-to-design-an-api-best-practises-concepts-technical-aspects/

ADD 2 - 关于RESTful

读了一些书后，我来到了这里：

  

RESTful架构只是集成的众多方法之一   应用。它利用Web标准，希望能够实现   集成简单而自然。资源由URL标识，   用HTTP方法操纵，并在某些序列化中传输   在综合政党方便时形成。

Answer 1

要创建Web API（即RESTful服务），您需要遵循REST原则。我认为这个链接可以为您提供有关RESTful服务/ Web API设计的一些提示：http://restlet.com/blog/2015/03/16/designing-a-web-api/。

简而言之，RESTful服务应该利用它们设计的HTTP方法：

• 方法GET：返回资源的状态
• 方法POST：对资源执行操作（在资源列表中创建元素，...）。注意不要在URL中使用操作名称（类似/elements/some-action-name），因为它不是RESTful。
• 方法PUT：更新资源的完整状态
• 方法PATCH：部分更新资源状态
• 方法DELETE：删除资源

您还需要注意，他们可以在不同级别申请，因此方法不会做同样的事情：

• 列表资源（例如，路径/elements）
• 元素资源（例如，路径/elements/{elementid}）

您必须考虑的其他重要事项是：

• 使用状态代码告诉客户端请求是否成功（2xx系列），因客户端（4xx系列）或服务器（5xx系列）而失败
• 利用HTTP标头。例如，标题Content-Type表示所使用的内容类型（例如，jSON的应用程序/ json）和Accept用于内容协商（如果需要）...

否则，您可以利用Swagger和RAML等格式来制作Web API。像Restlet Studio这样的工具可以很好地帮助在线创建REST服务的结构，获取相应的Swagger和RAML内容，甚至生成服务器骨架或客户端SDK。您可以注意到此工具仅遵循REST原则......

关于安全性，您需要利用Authorization标头。有几种策略：

• 基本的。用户名/密码使用Base64编码并在标题中发送。
• 基于令牌的一个。您可以查看此链接以获取更多详细信息：https://templth.wordpress.com/2015/01/05/implementing-authentication-with-tokens-for-restful-applications/
• 的OAuth2。请看这个链接：http://www.bubblecode.net/en/2013/03/10/understanding-oauth2/。

关于文件上传，您可以利用多部分内容。请看这个链接：http://restlet.com/blog/2015/10/27/implementing-file-upload-with-restlet-framework/。我们使用Restlet框架，但您可能会选择一些通用提示......

希望它可以帮到你， 亨利

Answer 2

在我看来，Rest-full API的概念有点模糊，我建议你看一下这篇文章http://martinfowler.com/articles/richardsonMaturityModel.html

没有多少公共休息 - 完全api实际上达到了讨论的级别3.一般的想法是围绕＆＃34;资源＆＃34;模拟你的api。您的应用程序处理并尊重正确的http动词。

至于工具我有点像https://apiary.io/它可以帮助你构建一个API并且也可以提供模拟响应