如何在微服务架构(HAL,ALPS)中正确设置Restful服务的文档

Question

我已经阅读了很多关于如何正确设置微服务的内容,而且我已经开始讨论一些最近的概念,包括:HAL,ALPS和HAL浏览器.我在历史上记录了利用Swagger UI的事情,但是,我逐渐明白URL中心不是正确的方式,我应该围绕资源和链接组织文档,这是新技术的用途.关于这些新概念,我有很多知识空白,所以我希望能够正确理解这些技术如何协同工作,以便我了解每个可以融入其中的技巧.

我目前的理解是:

HAL - 是JSON之上的一种额外格式,可让您通过链接浏览API.

ALPS - 这是JSON之上的一种额外格式,可以让我提供基于英语的描述来帮助描述我的资源

HAL浏览器 - 以资源和链接为中心的文档的Swagger UI替换.与HAL和ALPS一起使用？

我目前对这些技术的理解是准确还是缺乏某些方面？同样实现我并不完全理解ALPS和HAL如何一起交互.我知道hal + json格式和alps + json格式,但我还没有看到hal + alps + json格式.

我想澄清的最后一个方面是我应该如何公开这些资源.通常我总是专注于非常精益的json消息是围绕预期发送hal + json格式,还是我应该在另一个URL上托管这些端点专门用于类似于swagger/HAL浏览器的文档？

Answer 1

伙伴！您正在尝试在这里感知大量信息。让我尝试分步解释。

以文档为中心意味着服务之间的转换，是的，它应该被称为网络上的语义共享信息（或理解为数据类型）。

步骤：1 用于具有数据类型元数据和标准数据类型的服务的协议（http）可以是任何形式的超媒体，即 HTML、XML、JSON、HAL 等。例如下面所示的 JSON，它是带有链接的根文档。“todos”和“profile”都只是基于 HAL 的超媒体链接，HAL 仅增强您当前的 API。

{ "_links" : {
    "todos" : {
      "href" : "http://localhost:8080/todos"
    },
    "profile" : {
      "href" : "http://localhost:8080/alps"
    }
  }
}

请注意，它只是与可能指向资源语义的资源链接的链接。HAL 主要关注的是通过链接、属性和/或嵌入来链接资源/模板。上面解释的功能可供性主要是协议级别的共享数据类型的链接。

步骤：2 ALPS 是应用程序级别的可供性，这意味着在上面的 JSON 中我知道 Todo 是什么，但如何与其交互？要与 Todo 交互，需要进行应用程序级别的状态转换。考虑下面的“todo”JSON，它从链接导航并显示详细的额外关键字，例如“描述符”和“类型”（语义、安全、不安全等）。

“id”属性成为表示标识符。这些设置或规则用于应用独立的 ALPS 状态和转换。

{ "version" : "1.0",
  "descriptors" : [ {
    "id" : "todo-representation",
    "descriptors" : [ {
      "name" : "description",
      "doc" : {
        "value" : "Details about the TODO item",
        "format" : "TEXT"
      },
      "type" : "SEMANTIC"
    }, {
      "name" : "title",
      "doc" : {
        "value" : "Title for the TODO item",
        "format" : "TEXT"
      },
      "type" : "SEMANTIC"
    }, {
      "name" : "id",
      "type" : "SEMANTIC"
    } ]
  }, {
    "id" : "get-todos",
    "name" : "todos",
    "type" : "SAFE",
    "rt" : "#todo-representation"
  }, {
    "id" : "create-todos",
    "name" : "todos",
    "type" : "UNSAFE",
    "rt" : "#todo-representation"
  }, {
    "id" : "delete-todo",
    "name" : "todo",
    "type" : "IDEMPOTENT",
    "rt" : "#todo-representation"
  }, {
    "id" : "patch-todo",
    "name" : "todo",
    "type" : "UNSAFE",
    "rt" : "#todo-representation"
  }, {
    "id" : "get-todo",
    "name" : "todo",
    "type" : "SAFE",
    "rt" : "#todo-representation"
  } ]
}

一些链接值得查看有关 ALPS和Rest Example的详细幻灯片。希望这有助于您理解。