冲浪API Web：Web概念的演变

7970冲浪API Web：Web概念0Erik Wilde API学院，CATechnologies苏黎世，瑞士erik.wilde@ca.com0摘要0Web基于许多标准，这些标准共同构成了Web的表面：通过了解和支持这些标准，可以用已知的方式解决问题。Web上的这种一般设计模式与人类Web上的API完全相同：通过使用（不断发展的）一组标准，API开发人员无需重新发明轮子，开发人员也可以通过在各种API中以相同方式解决相同问题而受益。 WebAPI的不断发展的一组标准可以被视为API设计的一组构建块或词汇。WebConcepts是一个网站（webconcepts.info）和一个存储库（github.com/dret/webconcepts），可用于管理组织内如何使用这些构建块，从而有助于建立Web API设计文化。 WebConcepts的主要思想是促进对现有标准和技术的重用，从而使团队更容易理解一般情况下有哪些选项，以及在其组织内哪些选项是流行选择。0CCS概念0• 信息系统→Web服务；• 软件及其工程→文档；•通用和参考→计算标准，RFC和指南；0ACM参考格式：Erik Wilde。2018年。冲浪API Web：Web概念。在WWW'18Companion：2018年Web会议伴侣，2018年4月23日至27日，法国里昂。ACM，纽约，美国，6页。https://doi.org/10.1145/3184558.318874301 引言0WebAPI已成为Web的重要基石：它们以类似于常规Web页面以人类可访问的方式公开服务。 WebAPI与人类Web之间的主要区别之一在于多样性和复杂性。在人类Web上，访问（几乎）总是通过Web浏览器进行。虽然HTML5及其对更强大的浏览器应用程序的支持导致技术复杂性大大增加，但多样性仍然相对较小，大多数Web页面假定浏览器具有某种最低的CSS和脚本支持，并在这些假设未满足时最好有一些备用策略。01 HTML5规范集和CSS规范集现在总共超过200个规范。0本文发表在知识共享署名4.0国际许可证（CC BY4.0）下。作者保留在个人和公司网站上传播作品的权利，并附上适当的归属。WWW '18Companion，2018年4月23日至27日，法国里昂，© 2018IW3C2（国际万维网会议委员会），根据知识共享CC BY 4.0许可证发布。ACM ISBN978-1-4503-5640-4/18/04。https://doi.org/10.1145/3184558.31887430对于WebAPI来说，情况完全不同，没有任何被普遍接受和支持的标准，除了HTTP被用作连接客户端和服务器的协议。有时分歧非常深（例如，关于Web服务是否应该更好地使用RPC还是REST作为基本架构原则的意见分歧）。然而，尽管WebAPI的设计细节经常不同，但事实仍然存在一些共享基础，因为它们都基于URI [1]的通用基本原则进行资源识别，并通过HTTP[6]进行资源交互。除了URI /HTTP的基础之外，API的“语言”变得更加多样化。考虑到结构化数据的表示方式的简单问题：现在流行的结构化数据元模型可能是XML [3]，JSON [2]和RDF[4]。这些已经要求实现使用不同的工具集，以便可以解析和处理这些表示中的结构化数据。但除此之外，通常还存在标准化的模型，无论是作为容器格式还是作为用于构建更大词汇的构建块。无论如何，这些模型都成为API的“语言”的一部分：API的用户必须理解它们并按照预期使用它们。除了这些表示语言之外，Web还有一大批其他词汇，WebAPI可以使用这些词汇来设计和公开其服务。一个常见的例子是HTTP缓存[5]，在HTTP /1.1最近修订之后，它不再是核心规范的一部分，而是一个单独的规范，恰好定义了5个HTTP头字段，并在其自己的“缓存语言”中定义了额外的12个HTTP缓存指令（与Cache-ControlHTTP头字段一起使用），以及7个HTTP警告代码（与WarningHTTP头字段一起使用）。HTTP缓存的这个例子显示了规范（在本例中是IETF的RFC 7234[5]）定义了一个完整的附加“语言”，WebAPI可以利用它来改进其资源与高级缓存功能的使用方式。使用这种“缓存语言”具有使用标准的两个主要优点：•如果已经有一个标准覆盖了WebAPI应该公开的功能/特性，那么就没有必要重新发明轮子。•与WebAPI一起工作的开发人员不必学习API解决该问题的特定方式。如果他们了解标准，他们就理解了API的这个方面，并且可以使用可能存在的现有工具和库来支持该标准。通过设计URI和HTTP以及许多其他标准，Web能够在许多不同的地方提供这种重用。这也强调了Web之所以伟大的原因，是因为它建立在URI /HTTP的共享基础上，但是0开发者跟踪WWW 2018，2018年4月23日至27日，法国里昂7980仍然有额外的“语言”用于设计更好的WebAPI，通过允许更多的重用，从而使API设计人员更容易专注于确实需要特定设计的API的特定方面。02 统一接口的神话0如引言中所提到的，URI/HTTP是所有WebAPI的共享基础，因此所有WebAPI都公开了一个基本的统一接口：当您知道一个URI时，您应该能够通过HTTPOPTIONS来探测资源，然后从那里继续。虽然这在理论上是正确的，在WebAPI的实践中，许多不同的标准都会发挥作用，如引言所示。因此，对于WebAPI，开发人员知道API使用哪些标准（或者使用标准作为“API语言的构建块”）可以非常有用。这意味着除了用户确实可以即时探索“API的语言”（例如，与其所有资源进行交互并跟踪响应中的各种HTTP头字段，以了解该API的“HTTP头字段语言”），这种方法是低效的，使得开发人员难以理解API的语言。例如，上述提到的HTTP头字段是Web架构的一个复杂方面：大约有200个不同的头字段被（半）官方指定和注册，还有更多的头字段被特定的WebAPI发明并仅在这些API中使用。因此，任何WebAPI都可以使用许多不同的HTTP头字段，而要找出它使用的哪些字段通常并不容易。03 WEB API设计文化0在API领域，这个问题变得更加困难。现代组织有许多不同的团队在许多不同的API上工作，每个API都是一个设计练习的结果。随着微服务的兴起，团队被明确鼓励构建最适合他们正在构建的产品的API。微服务试图在增加团队速度的同时平衡团队的独立性，以实现至少一定程度的协调的API景观。现今的常规方法与API和SOAP的早期不同，早期的主要目标是通过标准化技术和工具集来创建统一性。经验表明，这种命令和控制的方法对团队来说过于限制，导致API开发缓慢和次优设计。微服务试图在增加团队独立性的同时提供他们成功所需的支持。例如，一个团队设计服务的典型例子是他们可能对组织内已经创建的类似问题和API感兴趣。这就是对组织内的设计文化的要求，对组织（团队可以建立在已有实践的基础上）和团队（团队可以建立在以前的经验上）都有用。此外，这种共享的设计文化允许组织在共享的“API语言”周围构建工具和支持。0例如，如果WebAPI对于主页文档或状态报告使用相同的表示方式，那么组织就可以更容易地构建适用于所有API的入口点或状态报告的工具。建立这种WebAPI设计文化对组织和个人团队都有帮助。需要注意的是，这种设计文化是流动的：它是团队使用的共享实践（即API构建块），就像IT中的任何事物一样，这些东西会随着时间的推移而改变。因此，设计文化的理想表示不仅仅是使用中的构建块的静态快照，还应该捕捉到它们的使用趋势随时间的变化。04 WEB CONCEPTS0本文的主要主题是Web Concepts。Web Concepts是WebAPI设计文化和实践的一部分，它由多个概念组成。撰写本文时，它包含了32个概念的730个不同值。其中一个例子是HTTP头字段的概念，有191种不同类型。其他概念的例子包括HTTP状态码、URI方案和媒体类型。该集合必然是不完整的，一方面是因为对于某些概念，有一组非常庞大的注册值，这些值在WebAPI中可能很少使用（例如，媒体类型就是这种情况），另一方面是因为当前的集合基于已发布或草案规范，并且在许多情况下，WebAPI会添加它们自己的私有概念，但从不注册或标准化它们（例如特定的HTTP头字段）。WebConcepts可在webconcepts.info和GitHub上的github.com/dret/webconcepts上获得，但数据的主要目的不是提供所有相关概念和值的权威概述，而是作为建立组织内设计文化和实践的起点。我们将在第7节中更详细地介绍如何重用WebConcepts，并在第8节中介绍如何使用它来跟踪API景观的演变。但首先重要的是看一下数据的组织方式，以及它如何表示Web概念的建立方式。05 WEB CONCEPTS MODEL0WebConcepts的基本模型非常简单：它假设规范建立了概念和值。目前，该网站的规范来自一些特定的组织，正如规范的数量所示，其中IETF和W3C占据了相当大的比重：0• 国际标准化组织（ISO）：3个规范 •互联网工程任务组（IETF）：214个规范 •Java社区流程（JCP）：1个规范 •结构化信息标准促进组织（OASIS）：4个规范 •万维网联盟（W3C）：40个规范0这种特定的混合受到IETF和W3C创建互联网和Web的基础规范的影响。如果我们看特定垂直的WebAPI，可能会使用来自专注于该垂直领域的组织的许多规范，这种情况可能会有所不同。这个情况会0开发者跟踪WWW 2018，2018年4月23日至27日，法国里昂the organizations listed above), and that combined these 262 speci-fication resources contain 730 values (combining the values for the32 concepts listed above).Adding values is done by adding specifications: A new resourceis created that represents the specification and the values it defines.Then the complete Web site (which is currently a static Jekyll site)is regenerated, and the new specification and values get added inthe various places where they are listed and linked.This model is describing how Web Concepts are managed andpublished as a site. However, the goal of Web concepts is to alsoserve as a machine-readable source of information about Web con-cepts, values, and specifications. To accomplish this goal, generatingthe Web site also generates JSON data that represents specificationsand Web concepts/values. These two JSON documents are inter-linked, and either one can serve as a starting point, depending onwhether one is mostly interested in specifications, or in concepts.5.1Specifications5.2ConceptsDevelopers Track WWW 2018, April 23-27, 2018, Lyon, France7990如果尝试表示可能不是“正确规范”，但在各种API中仍在使用的概念和值，它们也会有所不同。为了解决这个问题，WebConcepts将这些组织及其规范视为配置。可以轻松添加新组织，并在此之后可以添加这些组织定义的新概念和值的规范。规范的主要配置涉及命名约定以及在线访问和通过URI标识它们的方式。与组织一样，概念也可以轻松配置。撰写本文时，有32个概念，这些概念的值的数量差异很大，如下所示：0• HTTP身份验证方案（10） • HTTP缓存指令（15）• HTTP内容编码（10） • HTTP转发参数（4） •HTTP头字段（191） • HTTP首选项（4） •HTTP范围单位（3） • HTTP请求方法（39） •HTTP状态码（62） • HTTP传输编码（7） •HTTP警告代码（7） • JSON Web Token声明（8）• JWT确认方法（4） • 链接关系（98） •媒体类型（104） • OAuth访问令牌类型（2） •OAuth授权端点响应类型（2） •OAuth动态客户端注册元数据（20） •OAuth扩展错误（4） • OAuth参数（26） •OAuth令牌端点身份验证方法（3） •OAuth令牌检查响应（12） •OAuth令牌类型提示（2） • OAuth URIs（5） •PKCE代码挑战方法（2） • 档案URI（1） •结构化语法后缀（10） • URI方案（32） •URN命名空间（14） • 众所周知的URI（21） •XML命名空间（5） • XML模式（3）0添加Web概念值结合了规范和概念。对于每个规范，都会创建一个单独的资源。该资源描述规范本身（包括标题和摘要等简单元数据），然后包含一组值。对于每个值，规定了它所属的概念、值是什么、如何描述以及在线找到有关它的文档的位置。这意味着WebConcepts的当前状态由262个规范资源表示（结合了上述组织的规范），而这些262个规范资源合计包含了730个值（结合了上述32个概念的值）。通过添加规范来添加值：创建一个代表规范和定义的值的新资源。然后重新生成完整的网站（目前是一个静态的Jekyll网站），并在各个位置上添加新的规范和值的列表和链接。这个模型描述了WebConcepts如何管理和发布为一个网站。然而，Web概念的目标也是作为关于Web概念、值和规范的机器可读信息源。为了实现这个目标，生成的网站还会生成代表规范和Web概念/值的JSON数据。这两个JSON文档是相互关联的，可以根据兴趣的主要是规范还是概念来选择其中之一作为起点。0图1显示了规范的JSON表示形式。它是表示所有规范的更大JSON文档的一部分，只显示了一个示例（当前总共262个规范中的一个）。一般的结构是组织和规范系列，本例中组织是IETF，规范系列是他们的RFC出版流。组织和系列都有唯一的标识符，可以用于交叉引用规范和概念，也可以作为Web上可读的入口点。然后，每个单独的规范在系列中有一个标识符，并且再次具有用于交叉引用和人类可读的登陆页面的URI。规范还有一些与之关联的元数据，最重要的是标题和名称（以及摘要）。它还有一个由组织自己分配的URI标识符，以及一个（可能不同的）URL，用于访问规范在线。规范的核心信息是一个概念数组。每个概念由一个概念标识符（用于与下一节中描述的详细概念信息进行交叉引用）和一个值标识符来定义，后者也用于交叉引用目的。概念和值标识符都旨在与表示所有概念和值的JSON文档一起使用（但它们也作为Web表示的人类可读入口页面）。0所有概念和值都在第二个JSON文档中表示，类似于描述所有规范的规范JSON，描述所有概念和值。图2显示了该JSON文档的一部分，描述了一个值（当前总共730个概念值中的一个）。从当前配置的32个Web概念开始，JSON文档按概念结构化。每个概念都有一些与之关联的元数据，包括其单数和复数形式的名称，以及一个id（既是人类可读的资源，也是一个URI）。1{ "IETF":2{ "id":"http :// webconcepts.info/specs/IETF/",4"short": "IETF",5"series": [6{ "RFC":9"short": "RFC",10"specs": [11{ "2648":14"name":"RFC 2648",18"concepts": [6"values": [7{ "value":"GET",10"details": [8000图1：表示一个Web概念的JSON结构03 "name" : "互联网工程任务组" ,07 {  "id" : "http://webconcepts.info/specs/IETF/RFC/" ,08 "name" : "请求评论" ,012 {  "id" : "http://webconcepts.info/specs/IETF/RFC/2648" ,013 "title" : "用于IETF文档的URN命名空间" ,015 "URI" : "urn:ietf:rfc:2648" ,016 "URL" : "http://tools.ietf.org/html/rfc2648" ,017 "abstract" :  "一种用于统一资源名称（URN）的系统..." ,019 {  "http://webconcepts.info/concepts/urn-namespace" :020 "http://webconcepts.info/concepts/urn-namespace/ietf"  }]}}]}}]}}0列表2：表示一个概念的JSON结构01 {  "concept" : "http-method" ,02 "id" : "http://webconcepts.info/concepts/http-method/" ,03 "name-singular" :  "HTTP请求方法" ,04 "name-plural" : "HTTP请求方法" ,05 "registry" : "http://www.iana.org/assignments/http-methods/http-methods.xhtml#methods" ,08 "concept" :  "http://webconcepts.info/concepts/http-method/" ,09 "id" : "http://webconcepts.info/concepts/http-method/GET" ,011 {  "description" : "GET方法..." ,012 "documentation" :  "http://tools.ietf.org/html/rfc7231#section-4.3.1" ,013 "specification" :  "http://webconcepts.info/specs/IETF/RFC/7231" ,014 "spec-name" : "RFC 7231"  }]}]}0但也与在规范数据中使用的标识符相关联）。对于那些有官方维护的注册表的概念，链接也包括在其中。（值得一提的是，所有情况下官方注册表都不包含与当前WebConcepts网站上列出的完全相同的条目。原因是该网站还列出了许多已被提议的值，例如在互联网草案中，但尚未正式添加到注册表中。当组织使用WebConcepts作为其起点时，类似的情况也会发生，但然后添加他们使用的概念和值，并为其自己的API环境记录，但这些概念和值不打算永远输入官方注册表。）每个概念由一组值（从所有规范中收集）表示。其中每个值都有一个实际值，然后列出了概念标识符以及值id。0（这是一个可以与规范数据进行交叉引用的URI）。该值还包含详细信息，表示为数组，因为某些值在多个规范中定义。详细信息包含描述，指向在线文档的链接，并且为了方便交叉引用，还通过标识符和规范名称来标识规范。06 使用Web概念0WebConcepts的一个明显的用途是作为工具和文档中的辅助信息。例如，当一个工具专注于RESTAPI并且具有使用基本Web架构概念（如HTTP请求方法和状态码）的设计或编程抽象时，可以重复使用WebConcepts提供的信息，而不是手动编译此信息。0开发者追踪WWW 2018，2018年4月23日至27日，法国里昂3https://www.iana.org/protocols4https://github.com/for-GET/know-your-http-well8010使用Web Concepts时，有三种选择：0（1）一种选择是从网站下载JSON，从而创建当前现有选择的快照。这可以与偶尔的更新结合使用，但本质上仍然保持快照模型。（2）第二种选择是动态加载JSON，理想情况下与一些缓存机制结合使用，以便在网站更新时动态反映出任何更新。（3）第三种选择是克隆网站并单独控制其演变。这可以结合各种技术，如修剪内容、添加自定义规范，并定期从上游获取更改，以便最终在克隆中反映出网站的任何更改。0这些选项中没有一种在定义上比其他选项更好。这只是一个关于需要多少动态性和控制性的问题。然而，使用Web概念跟踪WebAPI标准发展的景观只是一个起点。当涉及到重用Web概念来创建定制版本时，事情变得更有趣，如下一节所述。07 重用Web概念0虽然Web概念可以简单地用于跟踪WebAPI标准的景观，但它也可以用作在组织中创建API的“设计语言”的起点。一个例子是组织内可能使用的特殊词汇。在某些情况下，这些可能会被Web级别的概念（如媒体类型）所覆盖。然而，可能还有其他情况，词汇在不同层级上使用，这些层级不一定是“一般的WebAPI景观”的一部分，比如RDF词汇。在这种情况下，添加其他概念可能是有用的，以便这些词汇可以成为可以跟踪的WebAPI景观的一部分。Web概念通过将概念和规范都视为可配置的方式使这变得容易。这意味着所需的只是添加一个新的概念（如“RDF词汇”），然后开始添加标识特定词汇的值。这些值可以由组织级文档进行标识和定义，添加到当前Web概念数据集所覆盖的标准组织的起点上。另一个例子可能是Kafka主题2这样的概念。在使用Kafka分布式流处理平台的组织中，主题是消息生成和消费的重要部分。然而，Kafka本身并不提供定义或管理主题的功能，它只是根据生产者和消费者的消息主题来组织消息分发。一个组织可能决定将Kafka主题转化为一个额外的Web概念，确保有一个地方可以在定义主题时进行注册，并且可以查找以了解正在使用哪些消息主题。02Kafka是一个开源的流处理软件平台，消息以发布-订阅的方式进行管理，消息的消费基于称为主题的消息标签。08 跟踪API景观的演变0通过WebConcepts，可以实现更高级的复杂性，不仅可以跟踪概念和值，还可以跟踪这些值在API中的使用情况。这将能够回答“我们的哪些API可能返回HTTP状态码451？”这个问题。可以通过所有组织的API来跟踪此信息，它们声称正在使用哪些Web概念，然后通过某些过程来consolida-ting该信息，以便在所有API中得到使用信息。这样做的一种可能方式是通过分散的过程从各个API发布的主页文档[7]中抓取使用信息。这个过程甚至可以提供历史数据，以表示API领域的趋势，比如哪些标准在API中的采用率逐渐增加或减少。这些信息对于寻找有关在设计API时要考虑哪些标准的开发团队来说是有用的：流行的标准可能是好的候选，而那些正在下降的标准可能不再是最佳设计选择。正如前面提到的，最终这将创建一个动态的图片，显示组织的API中正在使用哪些构建块，以及这个视图随时间的变化。这种洞察力可能是设计Web API的不断发展的最佳实践的有趣视角。09 相关工作0WebConcepts首先是一个资源，可以跟踪某些概念和对它们达成一致的值。它的起源是为了跟踪概念和标准，并能够在定义概念和值的各种组织的多样化环境中进行跟踪。虽然这个想法本身并不独特，但它的覆盖范围和可扩展性是独特的。对于不同的范围，存在其他资源。作为最古老和非常丰富的资源，有IANA的“协议注册表”列表，它部分重叠WebConcepts。然而，存在这样一个长期存在的问题，即这些数据没有以机器可读的格式公开，而且还存在它只涵盖由IANA定义或注册的值的额外问题。它还缺乏WebConcepts的更丰富数据模型，其中包含所有值的描述以及指向权威来源的链接。还存在其他针对性的努力。有一个名为“Know yourHTTP *well”的GitHub存储库，它维护了HTTP编码、头字段、方法、状态码以及媒体类型和链接关系的列表。虽然它与以结构化数据形式提供此信息的目标相同，但它在涵盖的概念方面较少。可能还有其他类似目标和方法的资源存在，但据本文作者所知，没有任何资源能够在概念覆盖范围、收集值的来源多样性和能够轻松扩展数据以添加新值或概念方面与Web Concepts相媲美。0开发者跟踪WWW 2018年4月23日至27日，法国里昂5http://unlicense.org/802010 治理0其中一个重要问题是如何管理规范集。对于由IETF或W3C等组织发布的新规范，可能有一些简单的答案。这些规范应该添加到主要的存储库中，目前的流程是通过PR和可能的后续讨论来完成。对于由较小组织制定的标准，它们可能没有那么可见和广泛使用，但只要它们被添加到相应的IANA注册表中，它们也是非常好的候选项。如果它们没有在IANA注册，只要有一份可以被引用和所有人都可以查阅的已发布规范，它们仍然可能是有价值的。对于那些被使用但既没有注册也没有在规范中定义的值，情况就会变得更加微妙。例如，许多WebAPI使用的HTTP头字段只有它们自己使用，虽然众所周知它们使用这些字段，但通常并没有真正的规范。WebConcepts目前的结构不允许不同级别的权威性，所以要么这些字段必须被添加为规范，要么它们必须被排除在外。将这种区分添加到WebConcepts可能是有趣的，但就像二进制系统一样，在某些情况下可能会变得棘手。最后，遵循通用的git数据管理模型，WebConcepts存储库可以根据需要进行克隆和调整（如第7节所讨论的）。这些克隆可以完全断开连接，或者它们的所有者可以选择从上游选择性地拉取更新，并可能将本地更新推送到上游。一般来说，WebConcepts旨在成为开放数据，并在“TheUnlicense”下发布。虽然该存储库目前是私有的，但任何人都可以轻松地进行分叉，并且可以随时随地进行分叉，如果有足够的兴趣，它可以轻松地变成一个GitHub组织（对于开源项目是免费的）。011 结论0本文描述了Web Concepts以及它们如何作为开发人员寻找理解APIWeb冲浪时流行的构建块的起点。WebConcepts的想法是提供一组开放且可重复使用的构建块，可以轻松地定制以代表组织对Web统一接口的模型。这样的视图可以帮助WebAPI的提供者和消费者，使他们能够更清楚地了解API的设计语言，并确保在组织内部，API构建块的重用成为一种已经确立并得到良好支持的实践。0参考文献0[1]  Tim Berners-Lee, Roy Thomas Fielding, and Larry Masinter.统一资源标识符（URI）：通用语法. 互联网RFC 3986, 2005年1月. [2]  Tim Bray.JavaScript对象表示法（JSON）数据交换格式. 互联网RFC 8259, 2017年12月. [3]  TimBray, Jean Paoli, C. Michael Sperberg-McQueen, Eve Maler, and FrançoisYergeau. 可扩展标记语言（XML）1.0（第五版）. 万维网联盟,推荐REC-xml-20081126, 2008年11月. [4]  Richard Cyganiak, David Wood, andMarkus Lanthaler. RDF 1.1概念和抽象语法. 万维网联盟,推荐REC-rdf11-concepts-20140225, 2014年2月. [5]  Roy Thomas Fielding, MarkNottingham, and Julian F. Reschke. 超文本传输协议（HTTP/1.1）：缓存. 互联网RFC7234, 2014年6月. [6]  Roy Thomas Fielding and Julian F. Reschke.超文本传输协议（HTTP/1.1）：消息语法和路由. 互联网RFC 7230, 2014年6月. [7]Mark Nottingham. 用于HTTP API的主页文档.互联网草案draft-nottingham-json-home-06, 2017年8月.02018年4月23日至27日，法国里昂举办的开发者论坛WWW 2018