Service Mapping Description(SMD)

摘要

服务描述语言(Service Mapping Descripton, SMD),是用JSON的展现形式来描述web服务的。一个SMD可以定义各种各样的web服务,使得客户端可以连贯的、有黏性的与web服务器之间进行交互。可以使用工具生成器来将SMD生成接口,有计划地访问可用的web服务。SMD可以描述包括REST和JSON—RPC在内的很广泛的web服务。SMD的格式是易扩展的、紧密而简洁的、可读的,也非常容易实现。

约定

本文中的关键字"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" 和 "OPTIONAL"的意思与RPC 2119中所解释的相同。

JSON Schema 是基于JSON的,因此它也具有与JSON相同的基本数据类型(详见:http://www.json.org/RFC 4627)。本文中所提到的任何JSON类型,第一个字母都是大写的: Object、Array、String、Number、True、False、Null。

需求

本文档是给那些服务提供商使用,用于正确的书写SMD,以及给web服务的客户端使用,用于正确的理解SMD并生成相应的方法来调用那些web服务的。SMD提供了关于那些可用服务的一些信息,但是服务器应该对它(SMD)所能使用的服务做限制,而且用户也可能会限制它(SMD)与服务器交流的可用类型。因此,本手册所定义的内容并不要求服务器端或客户端都完整实现,或解释每一个定义的服务类型和属性。

对于客户端来说,使用本手册的前提条件是,客户端要使用在一个SMD中描述的所有服务,并且要在定义中写出那些服务的非可选(non-optional)条件。客户端并不实现特定的服务类型,简单来讲可能并不需要实现那些服务。

对于服务器端来说,需要遵守的是,根据它的服务定义,那些服务必须具有某种形式的可操作性。不过,并不需要约定服务可以提供多少信息,因此也就并没有保证根据服务定义的某个服务请求一定会返回所希望的结果。服务器根据手册提供的服务信息越多,交互的层次就越高,客户端通过SMD所实现的服务也就越好。

SMD中包含有一些必要的属性,如果没有则不是合法的SMD。

术语

Service

是指一个web端点,它可以根据已定义的网络请求来执行某个操作,和/或返回指定的信息。

Method

是指一个subroutine,在本文中,它将执行一个服务,并根据服务所返回的值来返回数据。

详细说明手册

一个SMD被描述为带有属性的JSON对象,通过这些属性与可用的web服务进行交互。在SMD的根节点层,可以定义service属性和一个数组结构的methods属性,数组的元素与可用的服务一致。每一个服务可以有它自己的服务(service)属性。如果每个子属性并没有定义自己的service,那就就会继承根节点层的service属性。这样在SMD中,相同的service属性就可以只定义一次而共享了。所有的service属性都可选除非使用其他的方法声明。如下是可用的service属性:

transport

transport属性定义了在向服务器发送服务请求调用时所使用的传输机制。有如下预定义的属性值:

  • "POST" -- 使用HTTP POST方法向服务器端发送服务调用,服务信息包含在POST体内。
  • "GET" -- 使用HTTP GET方法向服务器端发送服务调用,服务信息包含在URL查询参数中。
  • "REST" -- 使用REST HTTP 方法(GET、POST、DELETE,以及POST)向服务器发送服务调用,服务信息包含在URL查询参数中。所有客户端都不是必须有权限使用所有可用的HTTP方法。PUT和POST方法同时需要有内容体(发送给服务器端)。
  • "JSONP" -- 使用HTTP GET方法向服务器端发送服务调用,服务信息包含在URL中,并使用标准的参数编码,并且返回的结果要使用JSONP协议添加回调函数。回调函数的名字应该使用jsonpCallbackParameter定义。
  • "TCP/IP" -- 这个服务的调用应该是直接构架在TCP/IP之上的。
  • "IFRAME" -- 发送到服务器的服务调用与使用JSONP传输相同,区别是返回内容应该包含在一个IFRAME中。Should the response automatically prepend the json call back parameter with "parent."?

transport属性默认使用POST

envelope

envelpe定义了从所提供的参数中创建服务消息字串的方法。

  • "URL" -- The response should be value returned from the method call. 例如:name=value 将会包含查询字串和请求体。URL编码参数允许使用相同名称的多个参数,所以建议你根据相同名称的多重参数进行罗列/写成数组。
  • "PATH" -- 参数应该包含在URL的路径中。例如:name/value将会添加在请求路径上。
  • "JSON" -- 参数将被转化为JSON字符串。例如:{"name":"value"}

示例

子服务(sub-services)定义的类型

子服务示例

Document Tags and Contributors

Contributors to this page: Carrie zhxj
最后编辑者: Carrie zhxj,