什么是超文本?

简单来说,超文本就是文本内容中带链接。最初是只读链接,就像看新闻网站时,点击一条新闻链接看具体内容。后来发展为读写链接,就像看完新闻写个评论。

什么是API?

API即应用程序编程接口,是提供给应用程序和开发人员调用的编程接口,通过API可以将不同的系统串连起来。

Web上设计超文本API

什么是Web API?大概是WebService的简化,去掉了对服务的定义和描述。

下面看一下对Web API响应数据的不同设计。

假如现在需要实现用户的增删改查功能,客户端不限,服务端可以使用以下几种方式响应客户端对用户列表的请求。

第一种:

1,tom,admin,active
2,mike,user,pending

这种方式返回数据量小,效率高。但是客户端必须自己实现解析程序,并且严格按照服务端的数据格式进行解析,服务端稍有变动,客户端就可能不能工作了。

第二种:

{
  users: [{
    id: 1,
    name: 'tom',
    role: 'admin',
    status: 'active'
  }, {
    id: 2,
    name: 'mike',
    role: 'user',
    status: 'pending'
  }
}

这种方式使用JSON数据返回,数据量比第一种要多了,但是JSON解析的工具很多,客户端不需要自己实现解析程序。到了这里,响应中已经包含了关于数据的元数据,即id、name、role等,可用于描述实际数据1、tom、admin等。但客户端获取到这些数据后,如果想要进一步动作,需要依赖客户端预定义的编码。比如,列表中只列出了主要信息,客户端想要获取某个用户的详细信息时,需要知道如何拼接出新的URL来做进一步请求。

第三种:

{
  users: [{
    name: 'tom',
    role: 'admin',
    status: 'active',
    uri: 'http://domain/users/1'
  }, {
    name: 'mike',
    role: 'user',
    status: 'pending',
    uri: 'http://domain/users/2'
  }
}

这里在第二种响应设计的基础上,增加了uri属性,用于标识出客户端获取明细信息的URI地址。这里有了链接,说起来便是超文本API了。

通过这个uri,客户端还可以依靠不同的HTTP Method(get、put、delete)来操作用户信息。

按照这样的思路做特定领域风格或一般领域风格的设计,客户端和服务端遵守一些基本的约定,如MIME类型、HTTP Method等,服务端和客户端的实现还是比较省力的。

但可能上面的设计还不够通用,这时第四种设计就出来了。

第四种:

{
  collection: [{
    links: [{
      rel: 'detail',
      href: 'http://domain/users/1',
      method: 'get'
    }],
    items: [
      {name: 'name', value: 'tom', prompt: 'Name'},
      {name: 'role', value: 'admin', prompt: 'Role'},
      {name: 'status', value: 'active', prompt: 'Status'}
    ]
  }, {
    links: [{
      rel: 'detail',
      href: 'http://domain/users/2',
      method: 'get'
    }],
    items: [
      {name: 'name', value: 'mike', prompt: 'Name'},
      {name: 'role', value: 'user', prompt: 'Role'},
      {name: 'status', value: 'pending', prompt: 'Status'}
    ]
  }]
}

这时已经领域无关了,如果客户端实现得比较好,那无论是用户信息管理,还是博客信息管理,都可以通过一个客户端来操作。

那么如果一个客户端可以操作服务端响应的任何数据,并且领域无关,不是用浏览器就好?于是就直接用HTML来设计API了。

第五种:

<div id="users">
  <ul class="all">
    <li>
      <span class="name">tom</span>
      <span class="role">admin</span>
      <span class="status">active</span>
      <a rel="detail" href="http://domain/users/1">detail</a>
    </li>
    <li>
      <span class="name">mike</span>
      <span class="role">user</span>
      <span class="status">pending</span>
      <a rel="detail" href="http://domain/users/2">detail</a>
    </li>
  </ul>

  <form method="post" action="http://domain/users" class="user-add">
    <input type="text" name="name" value="" required="true"/>
    <input type="text" name="role" value="" required="true"/>
    <input type="password" name="password" value="" required="true"/>
    <input type="submit" value="Create"/>
  </form>
</div>

使用HTML来设计API最大的好处就是可以直接用浏览器来完成测试,并且可以基本完成应用的处理流程,配以简单的CSS,在浏览器上可以像看网页一样轻松浏览所有API。客户端仍可以通过AJAX或其他客户端程序,编程操作这些API,改善用户体验,优化操作流程。

但目前无论是开放平台还是企业内部使用的API,还没有看到这样的设计。


读《使用HTML5和Node构建超媒体API》