API描述、發(fā)現(xiàn)與檔案入門

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

Web API的下一階段

雖然Web API的實現(xiàn)正變得越來越普及，但在工具方面還缺乏一些被廣泛接受的標準，用以描述、發(fā)現(xiàn)，并且理解大量基于API的服務(wù)的意義。如何圍繞著API的“元層面”對工具進行定義與實現(xiàn)，這方面仍然存在著大量的機會。

從目前來看，在以下三個領(lǐng)域方面，人們持續(xù)地表現(xiàn)出關(guān)注的態(tài)度以及開展實際的工作。這幾個領(lǐng)域分別是：

描述

API描述指的是以一種讓人類與機器都可讀的形式對API進行描述，包括API的實現(xiàn)細節(jié)，例如資源與URL、表述格式（HTML、XML、JSON等等）、狀態(tài)碼以及輸入?yún)?shù)。在這一領(lǐng)域方面，有幾個關(guān)鍵的帶頭者正處于前沿的位置。

發(fā)現(xiàn)

API發(fā)現(xiàn)是指按照一些特定的條件（例如上線時間、許可、定價以及性能限制），尋找以及選擇能夠提供所需服務(wù)（例如購物、用戶管理等等）的Web API的過程。目前來說，這一過程主要還是由人類驅(qū)動的，但已經(jīng)出現(xiàn)了一些工具，試圖將這一過程中的某些部分實現(xiàn)自動化。

檔案

“檔案”一直以來都是圖書管理員與信息科學(xué)家所關(guān)注的內(nèi)容，它定義了API請求與響應(yīng)中所包含的詞匯表術(shù)語的含義與使用方式。隨著Web API的發(fā)展，檔案也重新獲得了技術(shù)人員的關(guān)注。雖然它依然是一種實驗性質(zhì)的思想，但有跡象顯示，API的提供者與設(shè)計者正在開始實現(xiàn)對Web API檔案的支持。

本文將對Web API元數(shù)據(jù)的這三個方面進行一次簡單的回顧，并指出每個領(lǐng)域中的關(guān)鍵性工具與發(fā)展趨勢。

描述API的實現(xiàn)

目前，對于API的設(shè)計與實現(xiàn)的關(guān)注主要集中于它的描述格式。如今經(jīng)常為人提及的格式包括Swagger、RAML以及API Blueprint，但其實現(xiàn)有的格式可以舉出長長的一列。這些格式各自采取了一種略有不同的設(shè)計方式，但在本質(zhì)上都提供了相同的基本特性：以多種不同級別的細節(jié)對Web API進行描述。

API優(yōu)先

現(xiàn)如今，大多數(shù)設(shè)計方式都支持API優(yōu)先的概念。你首先以某種基于XML、JSON或YAML的元語言描述你的API，并通過生成的文檔（或文檔集）自動生成一些實現(xiàn)方面的元素，例如服務(wù)端代碼、人類可讀的文檔、測試harness、SDK，甚至是包含完整功能的API客戶端。

API優(yōu)先設(shè)計方式的一個例子是由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優(yōu)先方式時，你需要通過工具將設(shè)計時創(chuàng)建的元語言轉(zhuǎn)換為可以在運行時起作用的東西。舉例來說，Swagger的codegen工具能夠解析描述文檔，并生成相應(yīng)的客戶端代碼。而RAML-for-JAX-RS項目則在RAML描述與通過JAX-RS進行注解的Java代碼之間提供雙向轉(zhuǎn)換的功能。

代碼優(yōu)先

支持代碼優(yōu)先方式的描述模型為數(shù)極少，這種方式是通過源代碼生成服務(wù)描述。不過，這一領(lǐng)域中最知名的格式 ——?Web Service描述語言（WSDL）在企業(yè)級應(yīng)用社區(qū)中仍然相當流行，并且支持WSDL的工具為數(shù)眾多，像微軟的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>

如果選擇了代碼優(yōu)先方式，那么你就需要通過某些工具，將你的源代碼轉(zhuǎn)換為可重用的API描述元數(shù)據(jù)。Eclipse與Visual Studio都可以一鍵實現(xiàn)通過代碼生成WSDL文件。另外還有一些工具能夠讀取WSDL文件，并生成各種實現(xiàn)元素。例如SmartBear的SoapUI工具就能夠基于WSDL文件生成代碼、創(chuàng)建人類可讀的文檔，甚至是進行構(gòu)建與運行測試集等任務(wù)。