带有上下文参数的 REST 最佳实践 GET

Question

我们有一系列通过标识符提取资源的 REST 服务，但我们最近的任务是传递披露参数以保存审计。

有什么用...

GET entity/{id}

现在变成了...

GET entity/{id}?requestName=&requestingOrganization=&reasonForUse=&verificationMethod=&otherAuditDisclosureProperties....

entity 的状态不会改变并且仍然是幂等的，但是我们必须在每次调用时审核附加信息以便提供它。

首先想到的是构造一个主体，但这似乎不适合 GET。这是使用无意查询/过滤的查询参数的第二种方法。这些附加参数是在请求时捕获的真正上下文信息。这些等同于存在于 SOAP 主体之外的 SOAP 调用中的 SAML 属性(这让我认为可能是 header 属性)。

另请注意，此信息是中继的，因此提供的身份验证 token 是为调用的服务用户提供的，而不是上下文的实际身份。原始调用者的身份在周围的信任框架中是隐式信任的。

你会如何定义这个动词/路径？

Answer 1

也许是自定义 header :vnd.mycompany.myheader；将所需的所有参数以某种可解析的格式放置在其中:name1=value1;名称 2=值 2。您消除了查询字符串中的浪费。

跑题回应

我无法想象您向 API 用户询问此类主观信息的场景，这需要付出大量努力才能提供(因为它会根据请求而变化)并且对客户没有任何值(value)。它仅供您内部使用。最可能的结果是客户对这些值进行硬编码并在所有请求中重复它们。

如果客户端是内部客户端，您可能正在寻找关联跨多个服务的请求的方法，例如 Sleuth ，这将使您了解客户为何使用您的 API。

如果客户是外部客户，请考虑对开发人员进行调查和个人访谈。我还建议您首先培育您的 API 社区以接触这些人并了解他们如何以及为何使用您的 API。