Questions tagged «api-design»

我们有一个API函数，可根据给定的开始日期和结束日期将总金额细分为每月金额。 // JavaScript function convertToMonths(timePeriod) { // ... returns the given time period converted to months } function getPaymentBreakdown(total, startDate, endDate) { const numMonths = convertToMonths(endDate - startDate); return { numMonths, monthlyPayment: total / numMonths, }; } 最近，此API的消费者希望以其他方式指定日期范围：1）通过提供月数而不是结束日期，或2）通过提供每月付款并计算结束日期。为此，API小组将功能更改为以下内容： // JavaScript function addMonths(date, numMonths) { // ... returns a new date …

38 api-design 

我正在提议对一个架构很差的软件项目进行更改，该项目会遇到很多问题。在较高的层次上，该项目在前端使用了Angular，并使用了各种REST API。一切都很棒（我看不到需要更改我们的技术或工具）。问题在于，UI中的代码库比服务器端API大得多。大多数业务逻辑都存在于UI中，而REST API是与UI层的简单CRUD数据库接口。 例如，发给客户的POST将创建客户记录，而PUT将修改该客户。不多，也不少。但是，我们的业务逻辑要求更高。创建客户的一般过程所要做的不仅仅是插入1条数据库记录。它将在其他必要的表中提供数据，执行某些验证和计算等。我更愿意进行单个POST / PUT调用来封装所有这些行为，从而减轻使用方客户端的负担。 因此，我的观点是，这种总体编排应该驻留在服务器（我们拥有完全控制权，日志等）上，而不是UI上，但是一个反对意见是该方法将不再是RESTful。因此，当我的建议是继续使用现有的技术堆栈，但在代码所属的位置实现根本的转变时，我不确定如何最好地描述这种方法。

37 rest  api-design  enterprise-architecture 

当涉及JSON API时，将响应展平并避免嵌套JSON对象是一种好习惯吗？ 例如，假设我们有一个类似于IMDb的API，但用于视频游戏。有几个实体，分别是Game，Platform，ESRBRating和GamePlatformMap，它们映射了Game和Platform。 假设您请求/ game / 1来获取ID为1的游戏，并返回嵌套了平台和esrbRating的游戏对象。 { "id": 1, "title": "Game A", "publisher": "Publisher ABC", "developer": "Developer DEF", "releaseDate": "2015-01-01", "platforms": [ {"id":1,"name":"Xbox"}, {"id":2,"name":"Playstation"} ], "esrbRating": { "id": 1, "code": "E", "name": "Everyone" } } 如果您使用的是JPA / Hibernate之类的工具，并且将其设置为FETCH.EAGER，它可能会自动为您执行此操作。 另一个选择是简单地使用API​​并添加更多端点。 在这种情况下，当请求/ game / 1时，仅返回游戏对象。 { "id": 1, "title": "Game A", …

37 design  rest  api-design  json 

关于HTTP API响应是否有某种标准？ 看完这篇演讲后，我开始怀疑。我们正在工作中开发公共HTTP JSON API，并且在不需要严格要求时不返回任何内容（例如，当/ OK或相应的4XX或5XX代码返回PUT到/ resource / {id}时仅返回200），但是没有JSON正文） 我们应该返回{"success":true}像他们在上面的链接中讨论的那样的泛型，还是可以返回“ void”主体并使用http响应代码处理所有内容？

33 rest  api-design  http 

在讨论静态和实例方法时，我总是认为，这Sqrt()应该是数字类型的实例方法，而不是静态方法。这是为什么？显然，它对一个值有效。 // looks wrong to me var y = Math.Sqrt(x); // looks better to me var y = x.Sqrt(); 值类型显然可以具有实例方法，就像在许多语言中一样，有一个实例方法ToString()。 从评论中回答一些问题：为什么1.Sqrt()不合法？1.ToString()是。 某些语言不允许对值类型使用方法，但是某些语言可以。我正在谈论这些，包括Java，ECMAScript，C＃和Python（已__str__(self)定义）。这同样适用于其他功能，例如ceil()，floor()等等。

31 programming-languages  language-design  history  api-design  math 

我正在设计使用微服务的应用程序，但不确定使用哪种最佳机制从多个服务收集数据。 我相信有两种选择： 集成了“服务间”通信机制，该机制允许服务直接对话。在将合并的响应返回给API网关之前，API网关将调用单个服务，然后再调用其他服务来收集数据。然后，API将响应返回给调用方。（当对serviceB的调用需要serviceA的响应时，这必须是同步调用。IE单独的人和地址服务。） 让API网关直接调用每个服务，并在返回响应之前合并API中的数据。 我倾向于第二种选择，因为使服务彼此交谈会引入耦合，在这种情况下，我最好还是构建一个整体应用程序。但是，使用此选项时，我可以想到一些严重的缺点： 让API执行对多个服务的多次调用会增加API服务器的负载，尤其是在其中某些调用处于阻塞状态时。 这种方法意味着API必须“知道”应用程序正在尝试做什么（IE Logic必须被编程到API中才能依次处理调用服务，然后合并数据），而不仅仅是充当微服务的愚蠢“终点”。 我想知道解决此问题的标准方法是什么，是否还有我遗漏的第三种选择？

30 architecture  api-design  microservices 

我正在评估一个库，其公共API当前如下所示： libengine.h /* Handle, used for all APIs */ typedef size_t enh; /* Create new engine instance; result returned in handle */ int en_open(int mode, enh *handle); /* Start an engine */ int en_start(enh handle); /* Add a new hook to the engine; hook handle returned in h2 */ int …

27 c  api-design  libraries 

此问题是从Stack Overflow 迁移而来的，因为可以在Software Engineering Stack Exchange上回答。 迁移 8年前。 我需要在新网站中保留用户名。 这些通常分为三类 1）没有一个人名（例如：admin，user，service，help，root等） 2）我们可能想保留的超级著名人物或公司的名称 3）我们直接指定的其他名称。 如果前两个类别的用户名列表存在于某个地方，我可以使用它们，那将非常有帮助。 有人知道这样的名单吗？

26 database  design  data  api-design 

我正在考虑将整体式REST API移至微服务体系结构，并且对数据存储有些困惑。如我所见，微服务的一些好处是： 水平可伸缩-我可以运行微服务的多个冗余副本以应对负载和/或服务器故障。 松散耦合-我可以更改微服务的内部实现而不必更改其他服务，并且我可以独立部署和更改它们等。 我的问题是数据存储。在我看来，有几种选择： 所有微服务共享一个数据库服务-这似乎完全消除了松耦合的任何好处。 每个微服务上的本地安装的数据库实例-我看不到横向扩展此方法的方法，因此我认为这不是一个选择。 每个微服务都有自己的数据库服务-这似乎是最有前途的，因为它保留了松散耦合和水平扩展的优势（使用冗余数据库副本和/或跨多个分片） 在我看来，第三种选择似乎是唯一的选择，但是对我来说，这似乎是难以置信的沉重负担，并且是一种过度设计的解决方案。如果我理解正确，那么对于具有4-5个微服务的简单应用程序，我将必须运行16-20台服务器-每个微服务两个实际的微服务实例（以防服务器故障，并且在不停机的情况下进行部署），以及每个微服务有两个数据库服务实例（如果发生服务器故障等）。 坦率地说，这似乎有些荒谬。要记住，一个现实的项目可能会提供4-5个以上的服务，而16-20个服务器运行一个简单的API，该不该？我是否缺少一些基本的概念来解释这一点？ 回答时可能会有所帮助的一些事情： 我是该项目的唯一开发人员，并将在可预见的将来。 我正在使用Node.js和MongoDB，但是我对与语言无关的答案很感兴趣-一个答案甚至可能是我使用了错误的技术！

25 architecture  rest  api-design  microservices 

创建RESTful API时，应该在相同的URL上使用HTTP动词（如果可能），还是在每个操作中创建特定的URL？ 例如： GET /items # Read all items GET /items/:id # Read one item POST /items # Create a new item PUT /items/:id # Update one item DELETE /items/:id # Delete one item 或使用特定的网址，例如： GET /items # Read all items GET /item/:id # Read one item POST /items/new # …

25 rest  api-design  web-api 

在我当前的项目中，我负责服务的实现，该服务涉及使用新创建的RESTful API，这些文档记录为仅支持JSON。 客户端始终使用“ application / json”的接受标头和“ application / json”的内容类型发出请求。但是，某些端点会发送带有HTML内容类型的响应，甚至是HTML正文。对我来说，这显然是错误的方法，永远无法辩解。 在整个项目中，相同的做法已应用于两个不同的供应商和两个不同的服务。我发现自己必须证明为什么需要更改服务。供应商表示，客户端应对此进行处理，甚至我选择的REST库也受到了质疑（RestEasy），因为默认情况下它不应对此问题。 这是一个主要的挫败点。我找不到很多引用来支持我的论点，我认为这是因为要点很明显，所以没有意义。 问题是，我缺少什么吗？我对此很腐吗？在这种情况下，可以使用不具有application / json内容类型的JSON API吗？参考将不胜感激。您如何从商业角度解决这种情况？

25 rest  api-design  json  bad-code 

在系统之间（业务级别）讨论API时，我们团队中通常有两种不同的观点：有些人更喜欢（可以说）通用抽象方法，而另一些则是直截了当的“具体”方法。 示例：设计一个简单的“人员搜索” API。具体的版本是 searchPerson(String name, boolean soundEx, String firstName, boolean soundEx, String dateOfBirth) 支持具体版本的人说： API是自我记录的 很容易理解 易于验证（编译器或作为Web服务：模式验证） 吻 我们团队中的另一组人会说“那只是搜索条件列表” searchPerson(List<SearchCriteria> criteria) 与 SearchCritera { String parameter, String value, Map<String, String> options } 可能使某些枚举类型的“参数”。 支持者说： 在不更改API（声明）的情况下，实现可以更改，例如添加更多条件或更多选项。即使在部署时也没有同步这样的更改。 即使使用具体的变体，也需要文档 模式验证被高估了，通常您需要进一步验证，模式无法处理所有情况 我们已经有一个与其他系统类似的API-重用 相反的论点是 有关有效参数和有效参数组合的大量文档 需要更多的沟通工作，因为其他团队更难以理解 有没有最佳做法？文献？

25 api  web-services  api-design 

我有一个需要维护的Rails平台。它基于其构建了许多不同的Web应用程序。但是，现在客户正在请求一个API，以便他们可以将用户保留在其站点上，但可以利用我们拥有的一些自动化任务。 该平台用于构建保险应用程序，并允许其在线购买，以及提供下载与您的保单相关的文档的方式。 所以我在构建API时的问题是： 当我必须做很多事情，比如validate，创建user，user profile和policy，几乎在同一时间。我应该进行4个单独的API调用，并让客户端在其端进行4个调用。还是我应该打一个电话，该电话除了很多参数之外，可以验证客户端并同时创建所有这三个对象，从而简化客户端的操作？ 在这种情况下，客户端可以同时获取所有必需的信息，因此它不像在其应用程序中有自然的流程那样暂停，它们可以对我的平台进行API调用。 在客户端上使用过许多API之前，我的直觉是尽可能简化客户端，让他们只进行一次调用。但是，这会导致functionsAPI 变得相当庞大，我也不喜欢这两者。 您如何建议我解决这个问题？ 需要注意的是，我对客户端能否实现复杂的API并不十分有信心。

25 web-applications  ruby-on-rails  api-design 

此问题已从“服务器故障” 迁移而来，因为可以在软件工程堆栈交换中进行回答。 迁移 6年前。 我目前正在实现HTTP API，这是我的第一次。 我已经花了很多时间在Wikipedia页面上查看HTTP状态代码，因为我决心在正确的情况下实现正确的代码。在该页面上列出的是编号为420的代码，这是Twitter用来限制速率的自定义代码。 但是，已经存在用于速率限制的代码。是429。 这使我想知道为什么在已经存在用例的情况下，他们为什么要设置自定义的呢？那只是可爱吗？如果是这样，那么在什么情况下可以接受返回不同的状态代码，客户可能会遇到什么问题呢？ 我在某个地方读到Mozilla并未实现笑话418: I’m a teapot响应，这使我认为客户端选择了他们实现的状态代码。如果这是真的，那么我可以想象Twitter的有趣之处可以增强您的冷静代码带来的麻烦。 除非我弄错了，否则我们可以使用任何代码号来表示我们喜欢的任何东西，并且只有约定表明404表示未找到，而429表示则很容易。

24 api-design  http 

我正在为一个项目设计REST API，在该项目中，用户始终处于多个“计划”之一中-每个计划都定义了一些资源限制，例如帐户可能拥有的最大用户数或他们可以上传的最大数据数。一旦达到这些限制之一，用户就可以升级他们的计划（基本上是付费）以获得更多资源。 我想返回一个特殊的状态代码，该状态代码表示由于帐户资源限制而无法执行操作的情况，因此升级计划将解决此问题-例如，如果用户使用了其存储容量的100％，并尝试上传其他文件，他们将收到此回复。 候选人是恕我直言： 403 Forbidden -但是，我想区分这种情况和其他情况，即用户只是缺乏执行此操作的权限。 401 Unauthorized -不是一个好主意，我们正在使用它来解决与身份验证相关的问题。 402 Payment Required -有道理，但我担心使用非标准但保留的状态码 甚至不太标准的423 Locked东西，例如将来我们不太可能将其用于其他任何东西 另一种选择是使用一些非常标准的东西，例如，403但在响应主体中指出错误的细节。 我想知道您相信哪种方法（a）从长远来看效果最好，并且（b）将更好地坚持RESTful原则。

24 rest  api-design  http