HAL 中的 HATEOAS POST 链接答案

【问题标题】：HATEOAS POST link in HALHAL 中的 HATEOAS POST 链接
【发布时间】：2018-05-08 10:55:12
【问题描述】：

如何在 HAL 中描述 POST 链接？

我正在设计一个带有 HATEOAS 约束的 RESTful API，类似于 Wikipedia's HATEOAS example，但用 HAL JSON 表示（为了清楚起见，删除了方案、主机等）：

GET /accounts/12345

{
  "id" : 12345,
  "balance" : 100.00
  "_links" : {
    "self" : {
      "href" : "/accounts/12345"
    },
    "transfer" : {
      "href" : "/accounts/12345/transfer{?amount,target}",
      "templated" : true
    }
  }
}

为了执行“转移”动作，客户端大概会这样做：

GET /accounts/12345/transfer?amount=100.00,target=54321

{
  "id" : 34567,
  "amount" : 100.00
  "_links" : {
    "self" : {
      "href" : "/transfers/34567"
    },
    "source" : {
      "href" : "/account/12345"
    },
    "target" : {
      "href" : "/account/54321"
    }
  }
}

通过 GET 调用“传输”链接会在“传输”中创建一个新资源。但是做一个 GET 来创建一个新资源并不是幂等的，它“感觉”是错误的；以 RESTful 资源为中心的 API 会发布：

POST {amount: 10.00, source: 12345, target: 54321}  /transfers/

{
  "id" : 34567,
  "amount" : 100.00
  "_links" : {
    "self" : {
      "href" : "/transfers/34567"
    },
    "source" : {
      "href" : "/account/12345"
    },
    "target" : {
      "href" : "/account/54321"
    }
  }
}

但是我如何在 HAL 中描述这个 POST 和所需的表单元素，以便客户端可以在不进行硬编码的情况下执行“正确的事情”？也许是这样的：

{
  "id" : 12345,
  "balance" : 100.00
  "_links" : {
    "self" : {
      "href" : "/accounts/12345"
    },
    "transfer" : {
      "href" : "/transfers{?amount,source,target}",
      "templated" : true,
      "method" : "POST"
    }
  }
}

但是method 不是HAL specification 的一部分，也没有类似的标识符——所以感觉我走错了路……

也许我的客户应该只是“知道”transfer 的 GET 会返回匹配的传输资源，而transfer 的 POST 会创建一个新的传输资源。

FWIW，我的实现使用带有 Spring HATEOAS 的 Spring Boot 2，所以后续问题是如何用 Spring HATEOAS 表达这一点......

【问题讨论】：

标签： java spring-boot hateoas spring-hateoas

【解决方案1】：

HAL 无法做到这一点。 HAL 的创建者 Mike Kelly，states on GitHub

执行此操作的“HAL 方式”是使用链接 rel 文档以人类可读的形式传达可用的方法。 IE。你的 barks 示例看起来像这样（注意“barks”链接 rel 现在是一个 URL）
{
   "_links": {
        "http://docs.example.com/barks": { "href": "/v1/dogs/1/barks" }
    }
}
如果开发人员在浏览器中获取 URL http://docs.example.com/barks，文档可以指定可用的方法、有效的请求正文、潜在的响应代码、响应正文等。然后开发人员会将其编码到她正在构建的客户端中.

这是 HAL 规范恕我直言的一个主要缺陷，但还有其他媒体类型可以解决此问题，例如 Mason 或 HAL 扩展 HAL-FORMS。尽管我不确定它们是如何与 Spring 集成的，但可能值得一试。

【讨论】：