api restful_HATEOAS的RESTful服务。记录超媒体API

川长思鸟来 2023-02-25 03:48 39阅读 0赞

api restful

## 1.简介 ##

希望本教程的前一部分不仅揭示了[超媒体][Link 1]和[HATEOAS][]的深远意义，而且使我们确信这些都是[RESTful][] Web服务和API的基本构建模块。 在这一部分中，我们将继续侧重于文档方面，以解决如何预先传递Web服务或API功能的问题。

### 目录 ###

1.简介 2. OpenAPI和朋友 3. OpenAPI不是答案，现在呢？

3.1。 应用程序级配置文件语义（ALPS） 3.2。 ALPS与JSON-LD，... 3.3。 JSON超模式 3.4。 微格式 3.5。 都柏林核心元数据计划（DCMI）

4。结论 5.下一步是什么

在进一步介绍之前，让我们根据[REST][RESTful]体系结构样式从服务提供者和服务使用者的角度详细说明手头的问题。 本质上， [超媒体][Link 1]驱动的Web服务和API的可发现性方面允许服务提供者发布单个URL，入口点并以此完成。 另一方面，任何[意识到超媒体的][Link 1]消费者都应该能够使用上下文链接浏览资源，并在必要时沿途完成任何所需的状态修改。 唯一的前提条件是提供者和消费者应该说相同的超媒体方言 。 这是关于提供者/消费者交互的机器角度，这是探索性客户端的示例。

现在，让我们从开发人员的角度来看这个问题。 您将如何知道特定资源的属性？ 您如何知道期望使用哪种类型的链接和链接关系？ 它支持的行动或能力如何？ 它们可能导致什么副作用？ 最后，作为开发人员，您只需要满足一个简单的要求，例如“客户**C**希望将其预订**R**再延长一周”。 这是人类对提供者/消费者交互的观点。

很多具有挑战性的问题，但是我们有答案吗？ 让我们找出……

## 2. OpenAPI和朋友 ##

如今，如果我们研究推荐用于记录[RESTful][] Web服务和API的推荐方法，那么毫无疑问，您将遇到[OpenAPI规范][OpenAPI] 。 该规范有多个版本，但在撰写本文时，最新版本是`3.0.2` 。

> [OpenAPI规范][OpenAPI] （ [OAS][OpenAPI] ）定义了与[RESTful][] API的语言无关的标准接口，使人类和计算机都可以发现和理解服务的功能，而无需访问源代码，文档或通过网络流量检查。 正确定义后，使用者可以使用最少的实现逻辑来理解远程服务并与之交互。
> 
> [https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md][https_github.com_OAI_OpenAPI-Specification_blob_master_versions_3.0.2.md]

公平地说， [OpenAPI][]是一个很好的规范，它是许多组织和个人出色的协作成果的结果。 它已被广泛认为是记录[RESTful][] Web服务和API的[首选][RESTful]方法，但它并不是唯一的方法。 其他良好的规范，例如[RAML][] ， [API蓝图][API] ， [RSDL][] ， [WADL][] ， [API Builder][] ， [iodocs][]和[tinyspec][]也在使用中，值得了解。

[OpenAPI][]和朋友可以完成这项工作，但是从根本上讲，这些规范集中在资源位置， [几乎没有][Link 2]或没有[超媒体][Link 1]支持。

就目前而言， [超媒体][Link 1]完全破坏了资源位置。 [超媒体][Link 1]驱动的[RESTful][] Web服务和API并非一成不变，远非如此，大多数机器或人类需要了解的内容都是在运行时共享的。

## 3. OpenAPI不是答案，现在呢？ ##

您可能经常碰到[超媒体][Link 1]将[RESTful][] Web服务和API转换为资源周围的状态机的说法。 从概念上讲，这是有道理的，因为[超媒体][Link 1]带来了状态和过渡的明确定义的语义。

而不是资源位置，我们应该专注于描述资源本身。 资源描述至少应包括其数据语义，受支持的可能动作（状态转换）（如果可能，取决于上下文）以及相关的可导航资源（具有关系类型的链接）。

### 应用程序级配置文件语义（ALPS） ###

[应用程序级配置文件语义][Link 3] （ [ALPS][Link 3] ）可能是最先进的，包含最广的规范，用于在[RESTful][] Web服务和API的上下文中记录和共享[超媒体][Link 1]的语义。

> [ALPS][Link 3]文档可以用作配置文件，以解释具有与应用程序无关的媒体类型（例如HTML， HAL ， Collection + JSON ， Siren等）的文档的应用程序语义。 这样可以提高配置文件在各种媒体类型之间的可重用性。
> 
> [http://www.alps.io/spec/index.html][http_www.alps.io_spec_index.html]

概要文件的作用是为人类和机器建立共享的结构化词汇表。 简而言之，概要文件允许定义数据和过渡的语义以及包含文档的能力。

> 使用通用媒体类型（HTML，Atom， Collection + JSON等）实现[超媒体][Link 1]客户端/服务器应用程序时，客户端和服务器实例需要共享对特定于域的信息的理解，例如数据元素名称，链接关系值，和状态传输参数。 该信息与正在实施的应用程序（例如，会计，联系人管理等）直接相关，而不是与表示中使用的媒体类型相关。
> 
> [http://www.alps.io/spec/index.html][http_www.alps.io_spec_index.html]

在本教程的上半部分，我们已经看到了许多实现[RESTful][] Web服务和API的规范，让我们尝试通过[ALPS][Link 3]支持来扩展其中之一（例如HAL ）。

$ 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"
        },
        "profiles": {
          "href": "https://rentals.jcg.com/alps"
        }
      }
    }

与案例研究中的示例相比，您可能会注意到服务器还返回了一个附加的链接`profiles` 。 让我们看看它的背后。

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

{                                                                
      "version": "1.0",                                             
      "doc": {                                                                                    
        "href": "https://rentals.jcg.com/documentation.html"        
      },                                                             
      "descriptor": [ {                                             
        "id": "customers",                                           
        "href": "https://rentals.jcg.com/alps/customers"               
      }, {                                                           
        "id": "reservations",                                        
        "href": "https://rentals.jcg.com/alps/reservations"            
      } ]                                                            
    }

到目前为止，我们已经发布了两个配置文件描述符， `customers`和`reservations` 。 让我们更深入地了解`reservations`配置文件描述符。

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

{                                            
      "version": "1.0",                         
      "descriptor": [ {                         
        "id": "reservation",                    
        "type": "SEMANTIC",                     
        "descriptor": [ {                       
          "id": "from",                         
          "type": "SEMANTIC"                    
          "href": "https://schema.org/Date"
        }, {                                     
          "id": "id",                           
          "type": "SEMANTIC"                    
          "href": "https://schema.org/Thing#identifier"
        }, {                                     
          "id": "to",                           
          "type": "SEMANTIC",
          "href": "https://schema.org/Date"
        }, {                                     
          "id": "vehicle",                      
          "type": "SEMANTIC",
          "href": "https://schema.org/Vehicle#name"
        } ]                                      
      }, {                                       
        "id": "create",                           
        "name": "reservations",                 
        "type": "UNSAFE",                         
        "rt": "#reservation"                    
      }, {                                       
        "id": "list",                           
        "name": "reservations",                 
        "type": "SAFE",                         
        "rt": "#reservation"                    
      }, {                                       
        "id": "customer",                       
        "name": "customer",                     
        "type": "SAFE",                         
        "href": "https://rentals.jcg.com/alps/customers"
        "rt": "#customer"                       
      }, {                                       
        "id": "update",                         
        "name": "reservation",                  
        "type": "IDEMPOTENT",                   
        "rt": "#reservation"                    
      }, {                                       
        "id": "delete",                         
        "name": "reservation",                  
        "type": "IDEMPOTENT",                   
        "rt": "#reservation"                    
      } ]                                        
    }

值得花一些时间并简要介绍一下此个人资料。 它概述的第一件事是`reservation`描述符，用于描述数据语义（属性及其类型）。 之后，将引入动作和过渡的描述符数量（ `create` ， `list` ， `delete` ， `update` ， `customer` ）。

附带说明一下，尽管在我们的示例中，概要文件是由应用程序制作的，但是[ALPS][Link 3]还具有[注册表][Link 4]概念（ [ALPS][Link 3]概要文件注册表），以允许概要文件定义被重用和引用。 已经从[schema.org][]定义中预先构建了大量[ALPS][Link 3]配置文件，并且可以从[http://alps.io/schema.org获得][http_alps.io_schema.org] 。

回到主题，让我们看一下使用HAL样式作为参考的[ALPS][Link 3]配置文件如何渗透到资源表示中。

{                                                                                            
      "id": "13e1892765c5",                                                                     
      "vehicle": "Honda Civic 2020",                                                            
      "from": "2020-01-01",                                                                     
      "to": "2020-01-05",                                                                       
      "_links": {                                                                               
        "profile": {                                                                               
          "href": "https://rentals.jcg.com/alps/reservations#reservation"                                      
        },                                                                                       
        "customer": {                                                                           
          "href": "https://rentals.jcg.com/customers/fed195a03e9d",
          "profile": "https://rentals.jcg.com/alps/customers#customer"
        },                                                                                       
        "self": {                                                                               
          "href": "https://rentals.jcg.com/reservations/13e1892765c5"                             
        }                                                                                        
      },                                                                                         
      "_templates": {                                                                           
      …
      }                                                                                          
    }

HAL文档已得到充实，包括指向各自资源配置文件的`profile` [链接关系][Link 5] 。 或者，有时可以看到Links头对于发回资源配置文件信息很有用。

Links: profile="https://rentals.jcg.com/alps/reservations#reservation"

总体而言， [ALPS][Link 3]规范是描述[RESTful][] Web服务和API的资源语义和转换的一种非常简单且人性化的方式。

### ALPS与JSON-LD，... ###

一些[超媒体][Link 1]规范对数据语义（词汇）具有一流的支持。 一个很好的例子是带有`@vocab`上下文定义的JSON-LD 。

{                                                               
      "@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"     
    }

当依赖[超媒体][Link 1]规范时，资源语义详细信息将作为资源表示的一部分。 无论如何，这是有价值的信息。 相反， [ALPS][Link 3]概要文件与资源表示形式和媒体类型分开存在，并且可以独立查询和解释。

### JSON超模式 ###

[JSON模式][JSON]是一种基于[JSON][JSON 1]的格式，用于描述[JSON][JSON 1]数据的结构。 [JSON Hyper-Schema][]规范具有指定超链接和与[超媒体][Link 1]相关的关键字的功能，从而丰富了[JSON Schema][JSON]词汇表。

> [JSON Hyper-Schema][]是一个[JSON Schema][JSON]词汇表，用于使用超链接注释[JSON][JSON 1]文档以及通过HTTP等超媒体环境处理和操纵远程[JSON][JSON 1]资源的说明。
> 
> [https://tools.ietf.org/html/draft-handrews-json-schema-hyperschema-02][https_tools.ietf.org_html_draft-handrews-json-schema-hyperschema-02]

与ALPS相比， [JSON Hyper-Schema][]提供了更为丰富的语义，用于描述数据，链接（关系）和操作（负担）。 以下示例只是为`reservation`资源构建[JSON Hyper-Schema][]的一种可能性。

{
        "title": "Reservation",
        "type": "object",
        "properties": {
            "id": {
                "title": "Unique Reservation identifier",
                "type": "string"
            },
            "vehicle": {
                "title": "Name of the vehicle",
                "type": "string"
            },
            "from": {
                "title": "Start date",
                "type": "date"
            },
            "to": {
                "title": "End date",
                "type": "date"
            }
        },
        "required" : ["from", "to", "vehicle"],
        "links": [
            {
                "rel": "self",
                "href": "{id}"
            },
            {
                "title": "Customer",
                "rel": "customer",
                "href": "/reservation/{id}/customer"
            },
            {
                "title": "Cancel Reservation",
                "rel": "delete",
                "href": "{id}",
                "method": "DELETE"
            },
            {
                "title": "Update Reservation",
                "rel": "update",
                "href": "{id}",
                "method": "PUT",
                "schema": {
                    "type": "object",
                    "properties": {
                        "vehicle": {
                            "title": "Name of the vehicle",
                            "type": "string"
                        },  
                        "from": {
                            "title": "Start date",
                            "type": "date"
                        },
                        "to": {
                            "title": "End date",
                            "type": "date"
                        }  
                    },
                    "required": ["vehicle", "to", "from"]
                }
            }
        ]
    }

突出的第一件事可能是每个链接和操作所具有的详细程度。 您可能会注意到的直接缺点之一是语义（例如， `delete`动作）与具体的指针（例如`href`模板）交织在一起。

### 微格式 ###

除了ALPS和JSON Hyper-Schema外 ，还有一些鲜为人知的规范，值得一提。 [微格式][Link 6]就是其中之一。

> [微格式][Link 6]是为人为先设计的，其次是为机器设计的， [微格式][Link 6]是一组基于现有标准和广泛采用的标准的简单，开放的数据格式。 [微格式][Link 6]并没有丢掉当今[有用的][Link 6]东西，而是首先通过适应当前的行为和使用模式来解决更简单的问题。
> 
> [http://microformats.org/wiki/about][http_microformats.org_wiki_about]

[微格式][Link 6]的最新版本称为[microformats2][] 。

> [Microformats2][microformats2]替代并替代了两种经典的[微格式][Link 6] （有时称为microformats1），并且结合了从[微数据][Link 7]和[RDFa中][RDFa]获得的经验教训。
> 
> [http://microformats.org/wiki/microformats2][microformats2]

[微格式][Link 6]的主要目标是[HTML][]媒体类型（ [语义HTML][HTML 1] ），因此它不一定最适合大多数[RESTful][] Web服务和API。

### 都柏林核心元数据计划（DCMI） ###

最初的[都柏林核心][Link 8]规范发布于1995年，是一组15个（最初为13个）核心元素，用于描述资源语义。 因此， [都柏林核心元数据计划][Link 9] （ [DCMI][Link 9] ）是一个旨在支持跨各种目的和业务模型的元数据设计和最佳实践创新的组织。 它定义了更丰富的规范[DCMI元数据术语][DCMI] 。

总的来说， [Dublin Core][Link 8]是致力于[应用程序配置文件][Link 10]和[链接数据][Link 11] （尤其是基于[RDF][]词汇表）的开拓性工作之一。 这些年来，它所管理[的规范数量][Link 12]已大大增加，不仅限于元数据。

与微格式一样 ，对于[RESTful][] Web服务和API来说， [都柏林核心][Link 8]和相关规范的广泛范围可能不是您的首选。

## 4。结论 ##

在本教程的这一部分中，我们讨论了用丰富的[超媒体][Link 1]支持来记录[RESTful][] Web服务和API的挑战。 公平地说，这是一个已解决的问题的说法远非事实。 [如今][OpenAPI] ， [OpenAPI][]规范已成为事实上的选择，但尚未[将超媒体][Link 1]视为一流的公民。 最杰出的替代方案，尤其是应用程序级配置文件语义（ALPS）和JSON Hyper-Schema ，无疑正在朝着正确的方向前进，但是这两种方案仍在进行中。

## 5.下一步是什么 ##

在本教程的下一部分中，我们将通过在JVM平台（使用Java）上设计和实现成熟的[RESTful][] Web服务API，从理论转向实践。

> 翻译自: [https://www.javacodegeeks.com/restful-services-with-hateoas-documenting-hypermedia-apis.html][https_www.javacodegeeks.com_restful-services-with-hateoas-documenting-hypermedia-apis.html]

api restful

[Link 1]: https://en.wikipedia.org/wiki/Hypermedia
[HATEOAS]: https://en.wikipedia.org/wiki/HATEOAS
[RESTful]: https://en.wikipedia.org/wiki/Representational_state_transfer
[OpenAPI]: https://github.com/OAI/OpenAPI-Specification
[https_github.com_OAI_OpenAPI-Specification_blob_master_versions_3.0.2.md]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md
[RAML]: http://raml.org/
[API]: https://apiblueprint.org/
[RSDL]: http://www.balisage.net/Proceedings/vol10/html/Robie01/BalisageVol10-Robie01.html
[WADL]: https://en.wikipedia.org/wiki/Web_Application_Description_Language
[API Builder]: https://app.apibuilder.io/
[iodocs]: https://github.com/mashery/iodocs
[tinyspec]: https://github.com/Ajaxy/tinyspec
[Link 2]: http://spec.openapis.org/oas/v3.0.3#link-object
[Link 3]: http://alps.io/
[http_www.alps.io_spec_index.html]: http://www.alps.io/spec/index.html
[Link 4]: http://alps.io/spec/profile-registry/
[schema.org]: https://schema.org/
[http_alps.io_schema.org]: http://alps.io/schema.org
[Link 5]: https://tools.ietf.org/html/rfc6906
[JSON]: https://json-schema.org/
[JSON 1]: https://www.json.org/
[JSON Hyper-Schema]: https://json-schema.org/draft-04/json-schema-hypermedia.html
[https_tools.ietf.org_html_draft-handrews-json-schema-hyperschema-02]: https://tools.ietf.org/html/draft-handrews-json-schema-hyperschema-02
[Link 6]: http://microformats.org/
[http_microformats.org_wiki_about]: http://microformats.org/wiki/about
[microformats2]: http://microformats.org/wiki/microformats2
[Link 7]: http://microformats.org/wiki/microdata
[RDFa]: http://microformats.org/wiki/RDFa
[HTML]: https://en.wikipedia.org/wiki/HTML
[HTML 1]: http://microformats.org/wiki/semantic-xhtml
[Link 8]: https://www.dublincore.org/
[Link 9]: https://www.dublincore.org/about/
[DCMI]: https://www.dublincore.org/specifications/dublin-core/dcmi-terms/
[Link 10]: http://www.ariadne.ac.uk/issue/25/app-profiles/
[Link 11]: https://en.wikipedia.org/wiki/Linked_data
[RDF]: https://en.wikipedia.org/wiki/Resource_Description_Framework
[Link 12]: https://www.dublincore.org/specifications/dublin-core/
[https_www.javacodegeeks.com_restful-services-with-hateoas-documenting-hypermedia-apis.html]: https://www.javacodegeeks.com/restful-services-with-hateoas-documenting-hypermedia-apis.html