restful rest_HATEOAS的RESTful服务。超媒体：REST的秘密要素

我不是女神ヾ 2023-02-25 03:51 59阅读 0赞

restful rest

在这篇文章中，我们将介绍有关HATEOAS的RESTful服务的综合文章。 超媒体是REST的秘密成分。

## 1.简介 ##

在本教程的前一部分中，我们花了一些时间来刷新有关[REST][]体系结构样式的基本原理的知识。 业界对[REST][]状态的批判性眼光揭示了一个令人失望的事实，即作为应用程序状态引擎（ [HATEOAS][] ）的[超媒体][Link 1] ，它的主要制约因素之一经常被完全省略。

### 目录 ###

1.简介 2.所有这些“噪音”是什么？ 3.野外的HATEOAS

3.1。 RFC 5988（网络链接） 3.2。 哈尔 3.3。 JSON：API 3.4。 JSON-LD 3.5。 警笛 3.6。 集合+ JSON 3.7。 优步 3.8。 亚哈皮 3.9。 石匠 3.10。 离子

4. HATEOAS的成本 5.案例研究 6。结论 7.接下来

> [超媒体][Link 1]由嵌入在信息表示中或作为信息表示之上的应用程序控制信息的存在来定义。 分布式超媒体允许将表示和控制信息存储在远程位置。
> 
> [https://www.ics.uci.edu/~fielding/pubs/dissertation/web\_arch\_domain.htm\#sec\_4\_1\_3][https_www.ics.uci.edu_fielding_pubs_dissertation_web_arch_domain.htm_sec_4_1_3]

这部分的主题是[超媒体][Link 1] ，尤其是[HATEOAS][] 。 希望我们不仅可以确信它的重要性，而且可以支持许多策略，以利用[超媒体][Link 1]功能丰富我们的[REST][] Web服务和API。

## 2.所有这些“噪音”是什么？ ##

众所周知，无状态是[REST][]体系结构风格的强制性约束之一。 另一方面，绝大多数现实世界的Web服务和API必须处理状态管理。 看起来[REST][]忽略了现代软件系统的现实和需求吗？

绝对不是， [REST][]体系结构风格承认状态管理的重要性，并以[超媒体][Link 1] （应用程序状态引擎）的形式提出了解决方案。 在服务器端， [超媒体][Link 1]的使用不仅通告了资源之间的关系，而且还通告了可能应用于该资源的动作。 在客户端， [超媒体][Link 1]的存在带来了可发现性方面的下一步行动，步骤或要进行的状态转换。 理想情况下，客户端只需要知道一个URI入口点，其他所有内容都可以通过[hypermedia][Link 1]来自服务器。

显然，客户端必须足够聪明，才能以可行的方式浏览[超媒体][Link 1]控件。 正如许多经验丰富的Web服务和API开发人员已经注意到的那样，对服务器的[超媒体][Link 1]支持并不那么困难，但是对客户端的支持却要困难得多。

但是，在Web服务和API的上下文中， [超媒体][Link 1]到底是什么？ 我们可以将其视为服务器随响应发送给客户端的附加元信息。 它主要包括相关资源的链接，最重要的是，适用于所讨论资源以更改其状态的上下文操作。

> 当我说超文本时，我的意思是信息和控件的同时呈现，从而使信息成为用户通过其获得选择和选择动作的能力。 超媒体只是文本在媒体流中包含时间锚点的扩展。 大多数研究人员都放弃了这一区别。
> 
> [https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven\#comment-718][https_roy.gbiv.com_untangled_2008_rest-apis-must-be-hypertext-driven_comment-718]

总之，这些元数据片段告诉客户端在哪里获取更多数据或在当前上下文中哪种操作有效。 如果您觉得这很刺激，那确实是。

因此，我们讨论了什么是[超媒体][Link 1]以及它在[REST][]体系结构风格中的重要地位，现在是时候讨论[超媒体][Link 1]的“方式”了。

## 3.野外的HATEOAS ##

仅重申我们在上一部分中所说的内容， [REST][]体系结构样式要求使用[超媒体][Link 1] ，但未指定如何使用它。 显然，这个漏洞必须关闭，并且多年来导致了各种样式和规格的泛滥。 许多公司走得更远，提出了自己的[超媒体][Link 1]类型，蓝图和建议。

> 超媒体类型是MIME媒体类型，其中包含导致应用程序流的本机超链接语义。 例如，HTML是一种超媒体类型。 XML不是。
> 
> [http://amundsen.com/hypermedia/][http_amundsen.com_hypermedia]

令人惊讶的是，到目前为止，还没有一个普遍接受的标准可以遵循，以使用[超媒体][Link 1]元素来授权Web服务和API。 一些或多或少被广泛采用，而另一些则占据相当狭窄的位置。 而且，大多数规范仍在发展之中，并且在进行中时被广告宣传。

为什么会有这么多规格，主要区别是什么？ 总的来说，弊端来自细节，更具体地说，在于描述相关的资源，链接和动作/操作。 如何找到最适合您的？ 坦白地说，选择合适的规范会直接影响支持该规范所需的工作量。 如果是未开发的Web服务或API，您几乎可以自由选择。 相比之下，当您维护现有的Web服务或API并通过[超媒体][Link 1]支持对其进行丰富的任务时，选择突然变得非常有限（除非您拥有完全重写的特权）。

从实现的角度来看，大多数规范都倾向于使用[JSON][]格式来表示资源状态和[超媒体][Link 1]控件。 但是，有些异常值会改用[HTTP][]协议标头。 这当然不是由[REST][]体系结构风格决定的，而是来自现代Web服务和API的现实，它们都是面向[HTTP][]的。

因此，这些规格是什么？

### RFC 5988（网络链接） ###

我们将从[RFC-5988：Web链接开始][RFC-5988_Web] 。 它指定Web链接的关系类型，为它们定义注册表，还定义[HTTP][]头中带有特殊`Link`头的此类链接的使用。 这是一个简单的示例：

Link: <https://rentals.jcg.com/reservations>; rel="self"; title="reservations"

当然，在`Link`标头（或多个`Link`标头）中可能编码了多个`Link` ，例如：

Link: <https://rentals.jcg.com/reservations?page=1>; rel="previous"; title="previous page", 
    <https://rentals.jcg.com/reservations?page=3>; rel="next"; title="next page"

[Web链接][RFC-5988_Web]是引入[超媒体][Link 1]支持的最基本，最简单的方法。 接受新的或现有的API相当简单，但是从功能的角度来看， [Web链接][RFC-5988_Web]提供的选项集非常有限，主要是简单的关系，并且不支持动作和集合 。

### 哈尔 ###

[JSON超媒体API语言][JSON_API]或[HAL][JSON_API]建立使用[JSON][]表示超媒体控件（链接和资源）的约定。 它由[Mike Kelly][]于2011年创建[。Web][Mike Kelly]服务和API发出[HAL][JSON_API]文档，以便客户端可以提取适当的链接，并根据它们的关系类型在它们之间进行导航。

尽管[HAL][JSON_API]规范仍处于[起草阶段][JSON_API] ，但其设计原理使其成为了由[超媒体][Link 1]驱动的现代Web服务和API的首选之一。

> HAL的主要设计目标是通用性和简单性。 HAL可以应用于许多不同的域，并施加了满足超媒体API关键要求所需的最少结构量。
> 
> [https://tools.ietf.org/id/draft-kelly-json-hal-02.html][JSON_API]

您可能会猜到，资源表示形式是[JSON][]格式的[HAL文档][HAL] ，这些[文档][HAL]使用专用的媒体类型`application/hal+json` 。

{
      "_embedded": {
        "reservations": [ {
          "id": "ce5886acbb87",
          "vehicle": "Volkswagen Golf 1.2 TSI",
          "from": "2020-02-01",
          "to": "2020-02-12",
          "_links": {
            "self": {
              "href": "https://rentals.jcg.com/reservations/ce5886acbb87"
            },
            "customer": {
              "href": "https://rentals.jcg.com/customers/fed195a03e9d"
            }
          }
        }, {
          "id": "fc14e8ef90f5",
          "vehicle": "BMW 325i",
          "from": "2020-01-10",
          "to": "2020-01-12",
          "_links": {
            "self": {
              "href": "https://rentals.jcg.com/reservations/fc14e8ef90f5"
            },
            "customer": {
              "href": "https://rentals.jcg.com/customers/fed195a03e9d"
            }
          }
        } ]
      },
      "_links": {
        "first": {
          "href": "https://rentals.jcg.com/reservations?page=0&size=10"
        },
        "self": {
          "href": "https://rentals.jcg.com/reservations?page=0&size=10"
        },
        "next": {
          "href": "https://rentals.jcg.com/reservations?page=1&size=10"
        },
        "last": {
          "href": "https://rentals.jcg.com/reservations?page=1&size=10"
        }
      },
      "page": {
        "size": 10,
        "totalElements": 13,
        "totalPages": 2,
        "number": 0
      }
    }

除此之外， [HAL还][JSON_API]支持URI模板和链接关系文档。 不幸的是， [HAL][JSON_API]不提供任何行动支持（您可能听说过的另一个名字是[Provided][] ）。 试图填补[HAL][JSON_API]空白的衍生规范之一是[HAL-FORMS][] 。 从本质上讲，它只是[HAL][JSON_API]的扩展，通过表达方法和属性的能力来增强它。

{                                                                       
      "id": "13e1892765c5",                                                
      "vehicle": "Honda Civic 2020",                                       
      "from": "2020-01-01",                                                
      "to": "2020-01-05",                                                  
      "_links": {                                                          
        "customer": {                                                      
          "href": "https://rentals.jcg.com/customers/fed195a03e9d"           
        },                                                                  
        "self": {                                                          
          "href": "https://rentals.jcg.com/reservations/13e1892765c5"        
        }                                                                   
      },                                                                    
      "_templates": {                                                      
        "default": {                                                       
          "method": "put",                                                 
          "properties": [ {                                                
            "name": "from",
            "regex" : "yyyy-MM-dd",
            "required": true
          }, {                                                              
            "name": "to",
            "regex" : "yyyy-MM-dd",
            "required": true
          }, {                                                              
            "name": "vehicle"                                              
          } ]                                                               
        },                                                                  
        "delete": {                                                        
          "method": "delete",                                              
          "properties": [ ]                                                
        }                                                                   
      }                                                                     
    }

请注意， [HAL-FORMS][]旨在仅显示针对同一资源（或URI）可用的操作。 如果是[JSON][]表示形式，则会为[HAL-FORMS][]分配专用的媒体类型`application/prs.hal-forms+json` 。

### JSON：API ###

[JSON：API][JSON_API 1]是受[超媒体][Link 1]支持的Web服务和API的最广泛支持的标准之一。 它最初是由[Yehuda Katz][]于[2013年][2013]起草的，此后越来越受欢迎。 您可能会猜到，它仅适用于[JSON][]表示形式。

> [JSON：API][JSON_API 1]旨在最大程度地减少请求数量和客户端与服务器之间传输的数据量。 在不影响可读性，灵活性或可发现性的情况下实现了这种效率。
> 
> [https://jsonapi.org/format/][JSON_API 1]

[JSON：API][JSON_API 1]规范描述了链接，资源关系和资源修改（相当于动作）的语义。 另外，它涵盖了表示错误的方式。

{                                                                                                             
      "data": {                                                                                                  
        "id": "13e1892765c5",                                                                                    
        "type": "reservation",                                                                                   
        "links": {                                                                                               
          "self": "https://rentals.jcg.com/reservations/13e1892765c5"
        },                                                                                                        
        "attributes": {                                                                                          
          "from": "2020-01-01",                                                                                  
          "to": "2020-01-05",                                                                                    
          "vehicle": "Honda Civic 2020"                                                                          
        },                                                                                                        
        "relationships": {                                                                                       
          "customer": {                                                                                          
            "links": {                                                                                           
              "self": "https://rentals.jcg.com/reservations/13e1892765c5/relationships/customer",              
              "related": "https://rentals.jcg.com/reservations/13e1892765c5/customer"                          
            }                                                                                                     
          }                                                                                                       
        }                                                                                                         
      }
    }

使[JSON：API][JSON_API 1]脱颖而出的原因在于，考虑了诸如排序，过滤，稀疏字段集和分页之类的获取（查询）模式，这些模式也是规范的一部分。

{
      "data": [
        {
          "id": "ce5886acbb87",
          "type": "reservation",
          "links": {
            "self": "https://rentals.jcg.com/reservations/ce5886acbb87"
          },
          "attributes": {
            "from": "2020-01-01",
            "to": "0120-01-12",
            "vehicle": "Volkswagen Golf 1.2 TSI"
          },
          "relationships": {
            "customer": {
              "links": {
                "self": "https://rentals.jcg.com/reservations/ce5886acbb87/relationships/customer",
                "related": "https://rentals.jcg.com/reservations/ce5886acbb87/customer"
              }
            }
          }
        },
        {
          "id": "fc14e8ef90f5",
          "type": "reservation",
          "links": {
            "self": "https://rentals.jcg.com/reservations/fc14e8ef90f5"
          },
          "attributes": {
            "from": "2020-01-10",
            "to": "2020-01-12",
            "vehicle": "BMW 325i"
          },
          "relationships": {
            "customer": {
              "links": {
                "self": "https://rentals.jcg.com/reservations/fc14e8ef90f5/relationships/customer",
                "related": "https://rentals.jcg.com/reservations/fc14e8ef90f5/customer"
              }
            }
          }
        }
      ],
      "links": {
        "first": "https://rentals.jcg.com/reservations?page[limit]=2",
        "last": "https://rentals.jcg.com/reservations?page[limit]=2&page[offset]=2",
        "next": "https://rentals.jcg.com/reservations?page[limit]=2&page[offset]=2"
      },
      "meta": {
        "totalResourceCount": 3
      }
    }

公平地说， [JSON：API][JSON_API 1]具有非常简单，可读和可理解的格式。 为了实现这种权衡，它做出了一些明智的决定。 例如，您不会直接在[JSON：API][JSON_API 1]文档中看到操作。 实际上，它们根据[HTTP][]协议是隐式和隐式的： `POST`用于创建， `PATCH`用于修改， `DELETE`用于删除。 这可能会给客户带来一些解释上的困难，例如， [PUT在哪里][PUT] ？

尽管[JSON：API][JSON_API 1]规范的1.0版在2015年崭露头角，但它正在积极地研究之中，并被认为是一个不断发展的文档。 [JSON：API][JSON_API 1]已正确注册了媒体类型名称`application/vnd.api+json`并且还拥有自己的[JSON模式][JSON 1] [定义][Link 2] 。

### JSON-LD ###

[JSON-LD][]是链接数据的基于[JSON][]的序列化，在2014年就获得了[W3C][]候选正式建议的地位。它可能是最活跃的社区，而该规范的最新版本[JSON-LD 1.1的][JSON-LD]字面意思是已发布。一个月前。 [JSON-LD][]设计背后的关键原则强调能够轻松集成到已经使用[JSON的][JSON]现有系统中，并使用[JSON-LD][]语义对其进行扩充而不会破坏已建立的联系的能力。

可以肯定地说， [JSON-LD][]比链接[媒体][Link 1]更多的是链接数据，而不是[超媒体，][Link 1]但是它具有丰富的表达信息，上下文和关系的能力非常符合某些[超媒体的][Link 1]承诺。

{                                                               
      "@context": {                                                
        "@vocab": "http://schema.org/"                             
      },                                                            
      "@type": "Reservation",                                      
      "id": "13e1892765c5",                             
      "vehicle": "Honda Civic 2020",                               
      "from": "2020-01-01",                      
      "to": "2020-01-05",                        
      "customer": {                                                
        "@id": "https://rentals.jcg.com/customers/fed195a03e9d"      
      },                                                            
      "@id": "https://rentals.jcg.com/reservations/13e1892765c5"     
    }

[JSON-LD][]的缺点之一是它缺乏对动作的支持。 [Hydra][]解决了[JSON-LD的][JSON-LD]主要缺点， [Hydra][]是[超媒体][Link 1]驱动的Web服务和API的词汇。

> [Hydra][]的基本思想是提供一个词汇表，使服务器可以将有效的状态转换通告给客户端。 然后，客户端可以使用此信息来构造[HTTP][]请求，以修改服务器的状态，从而实现某个所需的目标。
> 
> [http://www.hydra-cg.com/spec/latest/core/\#hydra-at-a-glance][http_www.hydra-cg.com_spec_latest_core_hydra-at-a-glance]

为了了解它是如何工作的，让我们看一下[JSON-LD][]文档的快速示例，该示例已经丰富了[Hydra][]语义。

{
      "@context": {
        "@vocab": "http://schema.org/",
        "hydra": "http://www.w3.org/ns/hydra/core#"
      },
      "@type": "hydra:Collection",
      "hydra:collection": [ {
        "@type": "hydra:Collection",
        "@id": "https://rentals.jcg.com/reservations",
        "hydra:manages": {
          "hydra:property": "self",
          "hydra:subject": "https://rentals.jcg.com/reservations"
        },
        "hydra:operation": [ {
          "hydra:method": "GET"
        } ]
      } ],
      "hydra:member": [ {
        "@type": "Reservation",
        "vehicle": "Volkswagen Golf 1.2 TSI",
        "from": "2020-02-01",
        "to": "2020-02-12",
        "customer": {
          "@id": "https://rentals.jcg.com/customers/fed195a03e9d",
          "hydra:operation": [ {
            "hydra:method": "GET"
          } ]
        },
        "@id": "https://rentals.jcg.com/reservations/ce5886acbb87",
        "hydra:operation": [ {
          "hydra:method": "GET"
        }, {
          "hydra:method": "PUT",
          "hydra:expects": {
            "@type": "UpdateReservation",
            "hydra:supportedProperty": [ {
              "hydra:property": "from"
            }, {
              "hydra:property": "to"
            }, {
              "hydra:property": "vehicle"
            } ]
          }
        }, {
          "hydra:method": "DELETE"
        } ],
        "id": "ce5886acbb87"
      }, {
        "@type": "Reservation",
        "vehicle": "BMW 325i",
        "from": "2020-01-10",
        "to": "2020-01-12",
        "customer": {
          "@id": "https://rentals.jcg.com/customers/fed195a03e9d",
          "hydra:operation": [ {
            "hydra:method": "GET"
          } ]
        },
        "@id": "https://rentals.jcg.com/reservations/fc14e8ef90f5",
        "hydra:operation": [ {
          "hydra:method": "GET"
        }, {
          "hydra:method": "PUT",
          "hydra:expects": {
            "@type": "UpdateReservation",
            "hydra:supportedProperty": [ {
              "hydra:property": "from"
            }, {
              "hydra:property": "to"
            }, {
              "hydra:property": "vehicle"
            } ]
          }
        }, {
          "hydra:method": "DELETE"
        } ],
        "id": "fc14e8ef90f5"
      } ],
      "hydra:totalItems": 3,
      "hydra:view": {
        "@type": "hydra:PartialCollectionView",
        "hydra:next": "https://rentals.jcg.com/reservations?page=1&size=2",
        "hydra:first": "https://rentals.jcg.com/reservations?page=0&size=2",
        "hydra:last": "https://rentals.jcg.com/reservations?page=1&size=2"
      }
    }

再重申一次， [JSON-LD][]的最强之处是数据链接。 与[Hydra][]结合使用，您的Web服务和API将获得全面的[超媒体][Link 1]功能，但是集成可能并不像人们期望的那么容易。 [JSON-LD][]具有保留的媒体`application/ld+json` 。

### 警笛 ###

[Siren][]由[Kevin Swiber][]于2012年撰写，是用于表示实体的超媒体规范。 [Siren][]词汇表中的实体是URI可寻址资源，具有与之关联的属性，操作和可导航链接。 值得注意的是， [Siren][]是专门为Web服务和API设计的，例如，动作可以直接映射到[HTTP][]协议动词。

{                                                                                                    
      "class": [ "reservation" ],                                                                       
      "properties": {                                                                                   
        "id": "13e1892765c5",                                                                
        "from": "2020-01-01",
        "to": "2020-01-05", 
        "vehicle": "Honda Civic 2020"                                                                   
      },                                                                                                 
      "entities": [ {                                                                                   
        "rel": [ "customer" ],                                                                          
        "href": "https://rentals.jcg.com/customers/fed195a03e9d"                                          
      }, {                                                                                               
        "class": [ "customer" ],                                                                        
        "rel": [ "http://schema.org/customer" ],                                                        
        "properties": {                                                                                 
          "firstName": "John",                                                                          
          "lastName": "Smith",                                                                          
          "id" : "fed195a03e9d"                                                                  
        }                                                                                                
      } ],                                                                                               
      "actions": [ {                                                                                    
        "name": "update",                                                                               
        "method": "PUT",                                                                                
        "href": "https://rentals.jcg.com/reservations/13e1892765c5",                                      
        "fields": [ {                                                                                   
          "name": "from",                                                                               
          "type": "date"                                                                                
        }, {                                                                                             
          "name": "to",                                                                                 
          "type": "date"                                                                                
        }, {                                                                                             
          "name": "vehicle",                                                                            
          "type": "text"                                                                                
        } ]                                                                                              
      }, {                                                                                               
        "name": "delete",                                                                               
        "method": "DELETE",                                                                             
        "href": "https://rentals.jcg.com/reservations/13e1892765c5"                                       
      } ],                                                                                               
      "links": [ {                                                                                      
        "rel": [ "self" ],                                                                              
        "href": "https://rentals.jcg.com/reservations/13e1892765c5"                                       
      } ]                                                                                                
    }

尽管[Siren][]年龄[较大][Siren] ，但仍被列为进行中的工作。 它本身不像HAL或JSON：API那样流行，但是它相对简单和Web API优先语义使其成为值得考虑的选择。 [Siren][] [JSON][]表示形式的媒体类型为`application/vnd.siren+json` 。

### 集合+ JSON ###

由[Mike Amundsen][]在2011年创建的[Collection + JSON][Collection _ JSON]规范旨在成为一种[超媒体][Link 1]类型，旨在支持读取，编写和查询简单集合。 它受到[Atom联合格式（RFC-4287）][Atom_RFC-4287]和[Atom发布协议（RFC-5023）的][Atom_RFC-5023]启发。 关于[Collection + JSON的][Collection _ JSON]一个有趣的事实是，它将所有内容都视为一个集合，因此，单个项目表示为一个元素的集合。

{
      "collection": {
        "version": "1.0",
        "href": "https://rentals.jcg.com/reservations/13e1892765c5",
        "links": [ {
          "rel": "customer",
          "href": "https://rentals.jcg.com/customers/fed195a03e9d"
        } ],
        "items": [ {
          "href": "https://rentals.jcg.com/reservations/13e1892765c5",
          "data": [ {
            "name": "from",
            "value": "2020-01-01"
          }, {
            "name": "id",
            "value": "13e1892765c5"
          }, {
            "name": "to",
            "value": "2020-01-05"
          }, {
            "name": "vehicle",
            "value": "Honda Civic 2020"
          } ],
          "links": [ {
            "rel": "customer",
            "href": "https://rentals.jcg.com/customers/fed195a03e9d"
          } ]
        } ],
        "template": {
          "data": [ {
            "name": "from",
            "value": ""
          }, {
            "name": "to",
            "value": ""
          }, {
            "name": "vehicle",
            "value": ""
          } ]
        }
      }
    }

您可能会猜到， [Collection + JSON][Collection _ JSON]标准非常适合列表和集合。 它还包括对[查询模板][Link 3] （链接和关系）和[写模板][Link 4] （操作）的支持，以及标准化的错误报告。

在某些时候， [Collection + JSON][Collection _ JSON]非常流行，但是与其他替代方案相比，它实现起来可能更加困难。 同样，对“一切都是收藏”的偏见是不直观的。

[Collection + JSON][Collection _ JSON]的媒体类型为`application/vnd.collection+json` 。

### 优步 ###

[UBER][] [超媒体][Link 1]类型描述了对简单状态转移和临时转移的支持。 它是由[Mike Amundsen][] （是Collection + JSON的作者）和[Irakli Nadareishvili][]于2014年左右共同创建的，同时针对XML和JSON变体。

那么，作者提出另一种[超媒体][Link 1]类型的动机是什么？ [迈克·阿蒙森][Mike Amundsen] （ [Mike Amundsen）的][Mike Amundsen]这则推文使推理过程更加清晰。

> Collection + JSON是高度结构化的CRUD格式。 HAL适用于内联超媒体， Siren具有丰富的obj模型。 UBER开放且极简。
> 
> [https://twitter.com/mamund/status/456508872832716800][https_twitter.com_mamund_status_456508872832716800]

[UBER][]文档支持链接关系，操作和错误报告机制。 该规范旨在与多种协议配合使用，但包含有关基于[HTTP][]的实现和解释的详细指南。

{
      "uber": {
        "version": "1.0",
        "data": [ {
          "name": "customer",
          "rel": [ "customer" ],
          "url": "https://rentals.jcg.com/customers/fed195a03e9d"
        }, {
          "name": "self",
          "rel": [ "self" ],
          "url": "https://rentals.jcg.com/reservations/13e1892765c5"
        }, {
          "name": "update",
          "rel": [ "update" ],
          "url": "https://rentals.jcg.com/reservations/13e1892765c5",
          "action": "replace",
          "model": "from={from}&to={to}&vehicle={vehicle}"
        }, {
          "name": "delete",
          "rel": [ "delete" ],
          "url": "https://rentals.jcg.com/reservations/13e1892765c5",
          "action": "remove",
          "model": ""
        }, {
          "name": "reservation",
          "data": [ {
            "name": "from",
            "value": "2020-01-01"
          }, {
            "name": "id",
            "value": "13e1892765c5"
          }, {
            "name": "to",
            "value": "2020-01-05"
          }, {
            "name": "vehicle",
            "value": "Honda Civic 2020"
          } ]
        } ]
      }
    }

自2016年以来，它仍被标记为草稿（准确地说是稳定的草稿），并且没有太大变化。它没有正式注册的媒体类型，因此，如果使用[JSON][]表示，则必须使用`application/vnd.amundsen-uber+json` 。

### 亚哈皮 ###

有许多鲜为人知的[超媒体][Link 1]规范仍然值得关注。 我们[将从][Link 5] 2014年首次发布的[Another Hypermedia（ish）API][Link 5]规范（ [Yahapi][Link 5] ）开始，该规范[本质上是启用][Link 5] [超媒体的][Link 1]约定的列表。

> 最后， [Yahapi][Link 5]只是使您的API看起来漂亮，简单且一致的首选项列表。
> 
> [https://github.com/Yahapi/yahapi][Link 5]

[Yahapi][Link 5]提供了有关分页，排序，部分结果和错误格式的准则列表，支持链接和关系，但不幸的是不支持操作。 它很少在野外发现并且不是真正活跃。 [Yahapi][Link 5]文档的媒体类型仅为`application/json` 。

### 石匠 ###

[Mason][]是一种基于[JSON][]的格式，用于[将超媒体][Link 1]元素引入经典的[JSON][]数据表示中。 特别是，它包括用于链接和动作的[超媒体][Link 1]元素以及标准化的错误处理。 [Mason][]在媒体类型注册表中注册为`application/vnd.mason+json` 。

### 离子 ###

[Ion][]将自身定位为[REST的][REST 1]一种基于JSON的直观[超媒体][Link 1]类型。 它涵盖了关系类型的链接以及使用[表单的操作][Link 6] 。 不幸的是，自2018年以来，该规范似乎处于Hibernate状态。分配给[Ion][]内容的媒体类型为`application/ion+json` 。

## 4. HATEOAS的成本 ##

此时，您应该对[将超媒体][Link 1]和[HATEOAS][]应用于[RESTful][REST] Web服务和API时的作用有一个很好的了解。 而且，如果您是从事典型企业项目的经验丰富的软件开发人员，您可能很难记得上一次遇到[HATEOAS][]时的情况。 让我们面对现实：没有人知道如何使用[超媒体][Link 1] 。

在[REST][REST 1]体系结构的上下文中， [HATEOAS][]是必须的，但它不是免费的，并且会产生成本，有时非常重要。 不仅在实施方面，而且在前期设计方面。 在这方面，服务器相对容易，但是客户端确实很辛苦（充其量您可能会获得`Link`标头的支持）。 实际上，这意味着即使您开发完美的[RESTful][REST] Web服务或API，其他开发人员也有很大可能选择完全不在其客户端中使用超媒体。

在本教程的这一部分中，我们讨论了许多不同的[超媒体][Link 1]规范。 除少数例外，其中大多数带有“进行中”或“不稳定”的标签。 总的来说，这意味着仍有黑暗的水域在航行，而您最终到达那里的机会很高。 这就是为什么要持续不断地创建新规范的原因之一。 显然，每个规范需要非常不同的设计和实现工作量。 希望您的编程语言或平台生态系统已经有了一些库和框架来帮助您入门，但总的来说并非如此。

在服务器和客户端之间的数据交换方面， [超媒体][Link 1]可能会导致更多往返，以获取链接和关系背后的其他详细信息。 由于需要包括链接和操作，这也可能导致资源表示的大小大大增加。

您可能会问自己一个有趣的问题，即[REST][REST 1]架构风格（尤其是[HATEOAS）][HATEOAS]如何与微服务架构融合？ 为了说明问题，请考虑一个只有两个微 `Customer Service`的系统，即`Customer Service`和`Reservation Service` 。 由于客户不需要任何额外的知识或前期知识，他们如何发现有多种服务？ `Reservation Service`将如何纳入与客户相关的[超媒体][Link 1]元素，反之亦然？ 很有可能由另一层（例如API网关或/和聚合器）负责，并且听起来确实不是一个简单的问题。

如果此时您不惧怕[超媒体][Link 1]和[HATEOAS][] ，请不要担心。 收益大大超过了所需的成本和精力，尤其是从长期来看。 作为对此的确认，让我们看一下简短而简单的案例研究。

## 5.案例研究 ##

我们将要分析的示例应用程序是一个汽车租赁平台，该平台目前仅实现两个[RESTful][REST] Web API来管理`reservations`和`customers` 。 与任何客户端共享的唯一知识是平台的入口点，出于演示目的，假设在伪造的URL `https://rentals.jcg.com`后面有服务器。

该端点仅接受[HTTP][] `GET`请求并返回[超媒体][Link 1]文档（使用HAL和[HAL-FORMS][] ），示例如下所示。

$ curl https://rentals.jcg.com/

{                                                        
      "_links": {                                           
        "self": {                                           
          "href": "https://rentals.jcg.com/"                  
        },                                                   
        "reservations": {                                   
          "href": "https://rentals.jcg.com/reservations"      
        },                                                   
        "customers" : {                                      
          "href": "https://rentals.jcg.com/customers"         
        }                                                    
      }                                                      
    }

[超媒体][Link 1]感知客户端一旦收到此类文档，便可以清楚地了解到可以从那里导航到两个链接： `reservations`和`customers` 。 在这种情况下，客户对`reservations`感兴趣，因此就去了那里。

$ curl -iv https://rentals.jcg.com/reservations

{
      "_embedded": {
        "reservations": [ {
          "id": "ce5886acbb87",
          "vehicle": "Volkswagen Golf 1.2 TSI",
          "from": "2020-02-01",
          "to": "2020-02-12",
          "_links": {
            "customer": {
              "href": "https://rentals.jcg.com/customers/fed195a03e9d"
            },
            "self": {
              "href": "https://rentals.jcg.com/reservations/ce5886acbb87"
            }
          },
          "_templates": {
            "default": {
              "method": "put",
              "properties": [ {
                "name": "from",
                "regex" : "yyyy-MM-dd",
                "required": true
              }, {
                "name": "to",
                "regex" : "yyyy-MM-dd",
                "required": true
              }, {
                "name": "vehicle",
                "required": true
              } ]
            },
            "delete": {
              "method": "delete",
              "properties": [ ]
            }
          }
        }, 
        ...
        ]
      },
      "_links": {
        "self": {
          "href": "https://rentals.jcg.com/reservations"
        }
      },
      "_templates": {
        "default": {
          "method": "post",
          "properties": [ {
            "name": "from",
            "regex" : "yyyy-MM-dd",
            "required": true
          }, {
            "name": "to",
            "regex" : "yyyy-MM-dd",
            "required": true
          }, {
            "name": "vehicle",
            "required": true
          } ]
        }
      }
    }

这次服务器返回强大的资源表示形式（为简单起见，集合中仅保留一个保留项），其中包含许多[超媒体][Link 1]元素，因此客户端有多种选择。

例如，通过检查`_templates` [超媒体][Link 1]元素，它发现它可以通过在有效负载中提交包含`from` ， `to`和`vehicle`属性的[HTTP][] `POST`请求来创建新的保留（因为它是[HAL-FORMS][] ，所以使用`application/x-www-form-urlencoded`表单编码）。 您可能会注意到，尽管存在一些约束，但没有任何迹象表明`from` ， `to`或`vehicle`属性的类型（字符串？日期？数字？）是什么。

"_templates": {
      "default": {
        "method": "post",
        "properties": [ {
          "name": "from",
          "regex" : "yyyy-MM-dd",
          "required": true
        }, {
          "name": "to",
          "regex" : "yyyy-MM-dd",
          "required": true
        }, {
          "name": "vehicle",
          "required": true
        } ]
      }
    }

备选地，客户端可以通过自省相关联的`_templates` [超媒体][Link 1]元素来表达对特定保留的兴趣。

"_templates": {
      "default": {
        "method": "put",
        "properties": [ {
          "name": "from",
          "regex" : "yyyy-MM-dd",
          "required": true
        }, {
          "name": "to",
          "regex" : "yyyy-MM-dd",
          "required": true
        }, {
          "name": "vehicle",
          "required": true
        } ]
      },
      "delete": {
        "method": "delete",
        "properties": [ ]
      }
    }

在这种情况下，服务器提供选择来使用[HTTP][] `PUT`请求（完全替换语义）来更新保留，或者使用[HTTP][] `DELETE`请求来完全删除特定的保留。

## 超媒体–结论 ##

在本教程的这一部分中，我们讨论了[超媒体][Link 1]和[HATEOAS][] ，这是任何[RESTful][REST] Web服务或API的组成部分。 [超媒体][Link 1]规范的前景并非一成不变，并且在不断变化。 我们进行了很多选择，但没有遇到明显的赢家。 这样做的原因是，每一个都有不同的权衡，您需要确定哪种[超媒体][Link 1]规范最适合您的应用程序需求。 上下文很重要，因此请认真对待。 您可能会发现有关[为API选择超媒体类型][API]的文章[\-HAL，JSON-LD，Collection + JSON，SIREN，噢，我的天哪！][API] 由[Kevin Sookocheff][]提供帮助。

## 7.接下来 ##

在本教程的下一部分中，我们将讨论文档在由[hypermedia][Link 1]支持的[RESTful][REST] Web服务和API的生命周期中的作用。

> 翻译自: [https://www.javacodegeeks.com/restful-services-with-hateoas-hypermedia-the-secret-ingredient-of-rest.html][https_www.javacodegeeks.com_restful-services-with-hateoas-hypermedia-the-secret-ingredient-of-rest.html]

restful rest

[REST]: https://en.wikipedia.org/wiki/Representational_state_transfer
[HATEOAS]: https://en.wikipedia.org/wiki/HATEOAS
[Link 1]: https://en.wikipedia.org/wiki/Hypermedia
[https_www.ics.uci.edu_fielding_pubs_dissertation_web_arch_domain.htm_sec_4_1_3]: https://www.ics.uci.edu/~fielding/pubs/dissertation/web_arch_domain.htm#sec_4_1_3
[https_roy.gbiv.com_untangled_2008_rest-apis-must-be-hypertext-driven_comment-718]: https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven#comment-718
[http_amundsen.com_hypermedia]: http://amundsen.com/hypermedia/
[JSON]: https://www.json.org/json-en.html
[HTTP]: https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol
[RFC-5988_Web]: https://tools.ietf.org/html/rfc5988
[JSON_API]: https://tools.ietf.org/id/draft-kelly-json-hal-02.html
[Mike Kelly]: https://tools.ietf.org/html/draft-kelly-json-hal-00
[HAL]: https://tools.ietf.org/id/draft-kelly-json-hal-02.html#json-hal-documents
[Provided]: http://amundsen.com/blog/archives/1109
[HAL-FORMS]: https://rwcbook.github.io/hal-forms/
[JSON_API 1]: https://jsonapi.org/format/
[Yehuda Katz]: https://twitter.com/wycats
[2013]: https://jsonapi.org/about/
[PUT]: https://jsonapi.org/faq/#wheres-put
[JSON 1]: https://json-schema.org
[Link 2]: http://jsonapi.org/schema
[JSON-LD]: https://www.w3.org/TR/json-ld/
[W3C]: https://www.w3.org/
[Hydra]: http://www.hydra-cg.com/spec/latest/core/
[http_www.hydra-cg.com_spec_latest_core_hydra-at-a-glance]: http://www.hydra-cg.com/spec/latest/core/#hydra-at-a-glance
[Siren]: https://github.com/kevinswiber/siren
[Kevin Swiber]: https://twitter.com/kevinswiber
[Mike Amundsen]: http://amundsen.com/
[Collection _ JSON]: http://amundsen.com/media-types/collection/
[Atom_RFC-4287]: https://tools.ietf.org/html/rfc4287
[Atom_RFC-5023]: https://tools.ietf.org/html/rfc5023
[Link 3]: http://amundsen.com/media-types/collection/format/#query-templates
[Link 4]: http://amundsen.com/media-types/collection/format/#objects-template
[UBER]: https://rawgit.com/uber-hypermedia/specification/master/uber-hypermedia.html
[Irakli Nadareishvili]: https://www.freshblurbs.com/
[https_twitter.com_mamund_status_456508872832716800]: https://twitter.com/mamund/status/456508872832716800
[Link 5]: https://github.com/Yahapi/yahapi
[Mason]: https://github.com/JornWildt/Mason/blob/master/Documentation/Mason-draft-2.md
[Ion]: https://ionspec.org/
[REST 1]: https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
[Link 6]: https://ionspec.org/#forms
[API]: https://sookocheff.com/post/api/on-choosing-a-hypermedia-format/
[Kevin Sookocheff]: https://sookocheff.com/
[https_www.javacodegeeks.com_restful-services-with-hateoas-hypermedia-the-secret-ingredient-of-rest.html]: https://www.javacodegeeks.com/restful-services-with-hateoas-hypermedia-the-secret-ingredient-of-rest.html