我开发了REST API。我想通过API本身提供请求参数。
这个想法的起源是"--generate-cli-skeleton" for aws cli。
您知道关于REST API端点返回请求参数的方式的任何名称或示例吗？
例如，添加特殊的请求标头以显示需要这样的骨架。
curl -X POST -H "Generate-Skeleton: True" https://exmaple.com/users
→{name: "", age: ""}
答案 0 :(得分：1)
我的脑海中仍然存在一个基本问题：为什么需要它？
在我看来，就REST而言，这听起来像是一种反模式。 REST是针对计算机而不是人类的可浏览Web定位的概括，尽管适用于Web的相同概念基本上也适用于遵循REST体系结构的应用程序。
大量CRUD服务允许通过POST请求创建新资源。这里，有效负载的语义由服务器定义。客户端需要有关如何创建此类有效负载的带外信息，或者服务器需要以某种方式教给客户端此类信息。在网络上，这是通过表单完成的。表单不仅定义了所需的数据输入，还定义了将有效载荷发送到的位置。在遵循REST架构样式的应用程序中也可以这样做。在这里，应将表单描述为服务器和客户端都使用和理解的自己的媒体类型，类似于服务器和浏览器知道并理解的HTML。在没有表示可以在REST体系结构中使用的表单的专用媒体类型的情况下，人们可以简单地重用HTML的表单功能，即
从服务器检索数据还应避免解释资源属于特定类型。这很容易使您陷入typed resource trap中。相反，应在客户端通知服务器有关其功能的情况下使用content-type negotiation，并且服务器尝试以客户端可以使用的表示形式进行响应。关于上述表单示例，客户端和服务器可以就application/form+json表示形式达成一致，其中服务器基本上以JSON语法返回与HTML表单类似的信息。但是，应注意自定义媒体类型。它们应尽可能通用，以适用于大量客户，否则很有可能对此类媒体类型的支持将非常有限。
与HATEOAS一起，它基本上增加了对link-relation names的支持并避免了URI的解析和解释，但仅使用它们来在目标端点上调用下一个操作，这是IMO REST体系结构强加于此的基本先决条件为了获得高度的脱钩，客户和服务器端可以自由逃避，而不必担心破坏客户并使客户对变化更加有力。
应用这些步骤后，资源几乎可以自我描述。如果做得正确，则不需要外部文档或其他带外信息，也不需要基于客户端的存根/骨架类来与API交互，因为最终URI和HTTP是客户端需要支持的必要接口。
如果您需要支持自定义标头，则服务器需要在没有那些标头的情况下通知客户端它会扩展标头。这类似于基本身份验证。客户端向服务器发送请求，服务器以401 Unauthorized响应作为响应，该响应包含诸如WWW-Authenticate: Basic realm="fooBar"之类的标头，该标头通知客户端服务器期望使用提及领域进行基本身份验证。许多客户端实现都知道，需要以username:password之类的形式输入用户名和密码/密钥，还需要使用base64编码并将其附加到Basic字符串中。通常，这通常是在背部进行的，而无需您的任何投入。但是，对于自定义标头，这可能不那么容易自动化。但是您仍然可以发出适当的错误代码，例如409 Conflict或422 Unprocessable Entity来通知客户端必需但缺少的标头。这样的自定义标头最好用媒体类型来描述，因为它们既包括交换的表示形式的语法描述也包括语义描述，包括可选标头。
如果您需要生成此类属性以生成客户端存根代码或配置，则几乎没有REST，而是更多的类似RPC的系统，该系统是为与API交互而量身定制的，但会失败任何其他端点。即使您更改了URI结构或交换的消息格式中的某些内容，此类客户端代码也可能会根据其内部情况轻易中断。这也非常类似于SOAP / WSDL客户端存根代码生成，后者可以检索服务的WSDL XML表示形式，生成一些存根类，然后针对这些接口实现。这里的问题通常是，如果在生成客户端存根代码之后在WSDL文件中进行了某些修改，则客户端需要重新生成存根类，并最终更新其客户端代码以与创建的接口进行交互。如果您唯一从中获得更新信息的渠道是您不经常访问的渠道（即维护者主页），那么这尤其麻烦。在大多数情况下，只有在服务已更新时，您才能看到问题。这是几年前发生的几次，这迫使我们向部署在各种客户端计算机上的应用程序进行一些更新，这花费了我们两个工作日来进行更新。
我希望您能明白为什么我将这视为REST的反模式，在这种情况下，服务器应将采取进一步措施所需的所有信息通知客户端，或为客户端提供缺少的信息和将其发送到服务器。
答案 1 :(得分：1)
您是否考虑过使用json-schema之类的东西？
如果您确实希望使用某种JSON模板进行请求，则它们不应位于资源可访问的同一uri上。
相反，您应该将API单独包含一部分，例如：
GET /templates/user <- to fetch a 'skeleton' as you call it
要发现这些模板，您可以从现有API的战术位置创建链接。这可能是指向相关模板的某个地方的Link:标头。