API描述、发现与档案入门

原文出处：http://www.infoq.com/cn/articles/description-discovery-profiles-primer

Web API的下一阶段

虽然Web API的实现正变得越来越普及，但在工具方面还缺乏一些被广泛接受的标准，用以描述、发现，并且理解大量基于API的服务的意义。如何围绕着API的“元层面”对工具进行定义与实现，这方面仍然存在着大量的机会。

从目前来看，在以下三个领域方面，人们持续地表现出关注的态度以及开展实际的工作。这几个领域分别是：

描述

API描述指的是以一种让人类与机器都可读的形式对API进行描述，包括API的实现细节，例如资源与URL、表述格式（HTML、XML、JSON等等）、状态码以及输入参数。在这一领域方面，有几个关键的带头者正处于前沿的位置。

发现

API发现是指按照一些特定的条件（例如上线时间、许可、定价以及性能限制），寻找以及选择能够提供所需服务（例如购物、用户管理等等）的Web API的过程。目前来说，这一过程主要还是由人类驱动的，但已经出现了一些工具，试图将这一过程中的某些部分实现自动化。

档案

“档案”一直以来都是图书管理员与信息科学家所关注的内容，它定义了API请求与响应中所包含的词汇表术语的含义与使用方式。随着Web API的发展，档案也重新获得了技术人员的关注。虽然它依然是一种实验性质的思想，但有迹象显示，API的提供者与设计者正在开始实现对Web API档案的支持。

本文将对Web API元数据的这三个方面进行一次简单的回顾，并指出每个领域中的关键性工具与发展趋势。

描述API的实现

目前，对于API的设计与实现的关注主要集中于它的描述格式。如今经常为人提及的格式包括Swagger、RAML以及API Blueprint，但其实现有的格式可以举出长长的一列。这些格式各自采取了一种略有不同的设计方式，但在本质上都提供了相同的基本特性：以多种不同级别的细节对Web API进行描述。

API优先

现如今，大多数设计方式都支持API优先的概念。你首先以某种基于XML、JSON或YAML的元语言描述你的API，并通过生成的文档（或文档集）自动生成一些实现方面的元素，例如服务端代码、人类可读的文档、测试harness、SDK，甚至是包含完整功能的API客户端。

API优先设计方式的一个例子是由Apiary所推出的API Blueprint格式。它是一种基于Markdown的格式，目标是支持人类可读的API描述，同时又保证它的机器可读性。在以下示例中，你可以看到一个单一的资源（/message），它支持GET与PUT两种方法。你还可以看到其中对人类可读的文本的支持，以描述操作该API的方法。

API Blueprint**描述示例**

FORMAT: 1A

# Resource and Actions API
This API example demonstrates how to define a resource with multiple actions.

# /message
This is our resource

## GET
Here we define an action using the `GET` HTTP request method.

As with every good action it should return a response

+ Response 200 (text/plain)

        Hello World!

## PUT
OK, let's add an update action and send a response back confirming the posting was a success

+ Request (text/plain)

        All your base are belong to us.

+ Response 204

RAML、Swagger以及其它一些类似格式的工作方式也是大同小异。

在采用API优先方式时，你需要通过工具将设计时创建的元语言转换为可以在运行时起作用的东西。举例来说，Swagger的codegen工具能够解析描述文档，并生成相应的客户端代码。而RAML-for-JAX-RS项目则在RAML描述与通过JAX-RS进行注解的Java代码之间提供双向转换的功能。

代码优先

支持代码优先方式的描述模型为数极少，这种方式是通过源代码生成服务描述。不过，这一领域中最知名的格式 —— Web Service描述语言（WSDL）在企业级应用社区中仍然相当流行，并且支持WSDL的工具为数众多，像微软的Visual Studio与Eclipse等常见的编辑平台都提供了对它的支持。

下面是通过WSDL对某个简单的Web API进行描述的一个示例。

HelloService WSDL**示例**

<definitions name="HelloService"
   targetNamespace="http://www.examples.com/wsdl/HelloService.wsdl"
   xmlns="http://schemas.xmlsoap.org/wsdl/"
   xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
   xmlns:tns="http://www.examples.com/wsdl/HelloService.wsdl"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema">

   <message name="SayHelloRequest">
      <part name="firstName" type="xsd:string"/>
   </message>

   <message name="SayHelloResponse">
      <part name="greeting" type="xsd:string"/>
   </message>

   <portType name="Hello_PortType">
      <operation name="sayHello">
         <input message="tns:SayHelloRequest"/>
         <output message="tns:SayHelloResponse"/>
      </operation>
   </portType>

   <binding name="Hello_Binding" type="tns:Hello_PortType">
      <soap:binding style="rpc"
         transport="http://schemas.xmlsoap.org/soap/http"/>
      <operation name="sayHello">
         <soap:operation soapAction="sayHello"/>
         <input>
            <soap:body
               encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
               namespace="urn:examples:helloservice"
               use="encoded"/>
         </input>

         <output>
            <soap:body
               encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
               namespace="urn:examples:helloservice"
               use="encoded"/>
         </output>
      </operation>
   </binding>

   <service name="Hello_Service">
      <documentation>WSDL File for HelloService</documentation>
      <port binding="tns:Hello_Binding" name="Hello_Port">
         <soap:address
            location="http://www.examples.com/SayHello/" />
      </port>
   </service>
</definitions>

如果选择了代码优先方式，那么你就需要通过某些工具，将你的源代码转换为可重用的API描述元数据。Eclipse与Visual Studio都可以一键实现通过代码生成WSDL文件。另外还有一些工具能够读取WSDL文件，并生成各种实现元素。例如SmartBear的SoapUI工具就能够基于WSDL文件生成代码、创建人类可读的文档，甚至是进行构建与运行测试集等任务。