Restful OData Protocol

Web服务有两种实现方式:

　　一是SOAP协议方式

　　二是REST方式。

SOAP是一套完整的实现Web服务的解决方案。这里有必要先简单了解SOAP方式的Web服务，然后对比SOAP方式，我们会发现REST方式欠缺了什么。

 

　　SOAP方式的Web服务中的Web服务描述语言（WSDL）和简单对象访问协议（SOAP）一起构成了SOAP方式下的Web服务的结构单元。客户端通过WSDL可以了解Web服务公开了那些可以被执行的方法以及Web服务可以发送或接收的消息格式（解决了公布访问资源方法的问题）。客户端按照SOAP将调用位于远程系统上的服务所需信息序列化为消息（解决了如何调用远程方法的问题）。注意WSDL描述的服务以及SOAP消息都是符合统一标准的，都是机器可读的.

　　WSDL基于XML格式，用来描述Web服务。WSDL文档可以看成是客户端和服务器之间的一个协约。使用WSDL工具，你可以自动处理这个过程，几乎不用手工编写代码就能够让应用程序整合新的服务。因此WSDL是Web服务体系结构的基础，因为它提供了一个通用语言，用来描述服务和整合这些服务的平台。

　　SOAP本身提供了与Web服务交换信息的方法。SOAP是序列化调用位于远程系统上的服务所需信息的标准方法，这些信息可以使用一种远程系统能够读懂的格式通过网络发送到远程系统，而不必关心远程系统运行于何种平台或者使用何种语言编写。SOAP以XML格式提供了一个简单、轻量的用于在分散或分布环境中交换结构化和类型信息的机制。实际上它通过提供一个有标准组件的包模型和在模块中编码数据的机制，定义了一个简单的表示应用程序语义的机制。

 

　　对照SOAP方式的Web服务，REST中没有用于描述资源（服务）列表，资源元数据的类似于WSDL的东东。所以有人在2009年提出了一个标准WADL去描述REST方式的Web服务，但至今没有被标准化。个人认为使用WSDL/WADL去描述REST方式的Web服务太别扭，这是典型的RPC思路，而REST是一种把服务抽象为资源的架构思想。用描述RPC的WSDL去描述REST方式的Web服务并不合适。我们需要其他策略去代替WSDL实现“公布访问资源方法的问题”。

由于没有类似于SOAP的权威性协议作为规范，因此各个网站的REST实现都自有一套，也正是因为这种各自实现的情况，在性能和可用性上会大大高于SOAP发布的web service，但细节方面有太多没有约束的地方，其统一通用方面远远不及SOAP。

举个例子：假设A组织，B组织都实现了Restful API来通过工号查询人员信息，因为没有统一的规范。

A的API 可能是这样：http://A/api/person/001

B的API 可能是这样：http://A/api/person/id=001

第三方客户端在实现远程调用的时候就必须考虑这些API的差异，分别查看A，B的API文档。

如果有个权威性协议作为规范做指导，规定这个API应该实现成下面这样，那么第三方客户端也只需按照这个标准去调用远程API，而不用查看A，B的API文档：

http://A/api/person/{001}

解释了这么多，就是为了引出：OData是这样的一个设计和使用Restful API 的权威性协议. OData定义了一些标准规则（像一个接口定义一堆方法一样），实现Restful API时候，必须实现这些标准规则（就像实现一个接口必须实现其所有方法一样）。第三方就可以根据Odata协议定义的规则去访问Restful API。

 

　　The Open Data Protocol (OData) enables the creation of REST-based data services, which allow resources, identified using Uniform Resource Locators (URLs) and defined in a data model, to be published and edited by Web clients using simple HTTP messages. This specification defines the core semantics and the behavioral aspects of the protocol.　　

Context URL

The context URL describes the content of the payload. It consists of the canonical metadata document URL and a fragment identifying the relevant portion of the metadata document.

Request payloads generally do not require context URLs as the type of the payload can generally be determined from the request URL.

For details on how the context URL is used to describe a payload, see the relevant sections in the particular format.

The following subsections describe how the context URL is constructed for each category of payload by providing a context URL template. The context URL template uses the following terms:

• {context-url} is the canonical resource path to the $metadata document,
• {entity-set} is the name of an entity set or path to a containment navigation property,
• {entity} is the canonical URL for an entity,
• {singleton} is the canonical URL for a singleton entity,
• {select-list} is an optional parenthesized comma-separated list of selected properties, functions and actions,
• {property-path} is the path to a structural property of the entity,
• {type-name} is a qualified type name,
• {/type-name} is an optional type-cast segment containing the qualified name of a derived type prefixed with a forward slash.

The full grammar for the context URL is defined in [OData-ABNF].

1 Service Document

Context URL template:

{context-url}

The context URL of the service document is the metadata document URL of the service.

Example 10: resource URL and corresponding context URL

http://host/service/

http://host/service/$metadata

2 Collection of Entities

Context URL template:

{context-url}#{entity-set}

{context-url}#Collection({type-name})

If all entities in the collection are members of one entity set, its name is the context URL fragment.

Example 11: resource URL and corresponding context URL

http://host/service/Customers

http://host/service/$metadata#Customers

If the entities are contained, then entity-set is the top-level entity set followed by the path to the containment navigation property of the containing entity.

Example 12: resource URL and corresponding context URL for contained entities

http://host/service/Orders(4711)/Items

http://host/service/$metadata#Orders(4711)/Items

If the entities in the response are not bound to a single entity set, such as from a function or action with no entity set path, a function import or action import with no specified entity set, or a navigation property with no navigation property binding, the context URL specifies the type of the returned entity collection.

3 Entity

Context URL template:

{context-url}#{entity-set}/$entity

{context-url}#{type-name}

If a response or response part is a single entity of the declared type of an entity set, /$entity is appended to the context URL.

Example 13: resource URL and corresponding context URL

http://host/service/Customers(1)

http://host/service/$metadata#Customers/$entity

If the entity is contained, then entity-set is the canonical URL for the containment navigation property of the containing entity, e.g. Orders(4711)/Items.

Example 14: resource URL and corresponding context URL for contained entity

http://host/service/Orders(4711)/Items(1)

http://host/service/$metadata#Orders(4711)/Items/$entity

If the response is not bound to a single entity set, such as an entity returned from a function or action with no entity set path, a function import or action import with no specified entity set, or a navigation property with no navigation property binding, the context URL specifies the type of the returned entity.

4 Singleton

Context URL template:

{context-url}#{singleton}

If a response or response part is a singleton, its name is the context URL fragment.

Example 15: resource URL and corresponding context URL

http://host/service/MainSupplier

http://host/service/$metadata#MainSupplier

5 Collection of Derived Entities

Context URL template:

{context-url}#{entity-set}{/type-name}

If an entity set consists exclusively of derived entities, a type-cast segment is added to the context URL.

Example 16: resource URL and corresponding context URL

http://host/service/Customers/Model.VipCustomer

http://host/service/$metadata#Customers/Model.VipCustomer

6 Derived Entity

Context URL template:

{context-url}#{entity-set}{/type-name}/$entity

If a response or response part is a single entity of a type derived from the declared type of an entity set, a type-cast segment is appended to the entity set name.

Example 17: resource URL and corresponding context URL

http://host/service/Customers(2)/Model.VipCustomer

http://host/service/$metadata#Customers/Model.VipCustomer/$entity

7 Collection of Projected Entities

Context URL templates:

{context-url}#{entity-set}{/type-name}{select-list}

{context-url}#Collection({type-name}){select-list}

If a result contains only a subset of properties, the parenthesized comma-separated list of the selected defined or dynamic properties, navigation properties, functions, and actions is appended to the {entity-set} after an optional type-cast segment, or the type of the entity collection if the response is not bound to a single entity set. The shortcut * represents the list of all structural properties. Properties defined on types derived from the declared type of the entity set (or type specified in the type-cast segment if specified) are prefixed with the qualified name of the derived type as defined in [OData-ABNF].

Example 18: resource URL and corresponding context URL

http://host/service/Customers?$select=Address,Orders

http://host/service/$metadata#Customers(Address,Orders)

8 Projected Entity

Context URL templates:

{context-url}#{entity-set}{/type-name}{select-list}/$entity

{context-url}#{singleton}{select-list}

{context-url}#{type-name}{select-list}

If a single entity contains a subset of properties, the parenthesized comma-separated list of the selected defined or dynamic properties, navigation properties, functions, and actions is appended to the {entity-set} after an optional type-cast segment and prior to appending /$entity. If the response is not bound to a single entity set, the {select-list} is instead appended to the {type-name} of the returned entity.

The shortcut * represents the list of all structural properties. Properties defined on types derived from the type of the entity set (or type specified in the type-cast segment if specified) are prefixed with the qualified name of the derived type as defined in [OData-ABNF]. Note that expanded properties are implicitly selected.

Example 19: resource URL and corresponding context URL

http://host/service/Customers(1)?$select=Name,Rating

http://host/service/$metadata#Customers(Name,Rating)/$entity

9 Collection of Projected Expanded Entities

Context URL template:

{context-url}#{entity-set}{/type-name}{select-list}

{context-url}#Collection({type-name}){select-list}

If a navigation property is explicitly selected, the parenthesized comma-separated list of properties includes the name of the selected navigation property with no parenthesis. If a $expand contains a nested $select, the navigation property appears suffixed with the parenthesized comma-separated list of properties selected (or expanded, containing a $select) from the related entities. Additionally, if the expansion is recursive for nested children, a plus sign (+) is infixed between the navigation property name and the list of properties.

Example 20: resource URL and corresponding context URL

http://host/service/Customers$select=Name&$expand=Address/Country

http://host/service/$metadata#Customers(Name,Address/Country)

Example 21: resource URL and corresponding context URL

http://host/service/Employees/Sales.Manager?$select=DirectReports
                &$expand=DirectReports($select=FirstName,LastName;$levels=4)

http://host/service/$metadata
                #Employees/Sales.Manager(DirectReports,
                                         DirectReports+(FirstName,LastName))

10 Projected Expanded Entity

Context URL template:

{context-url}#{entity-set}{/type-name}{select-list}/$entity

{context-url}#{singleton}{select-list}

{context-url}#{type-name}{select-list}

If a single entity is expanded and projected (or contains a $expand with a $select expand option), the parenthesized comma-separated list of selected properties includes the name of the expanded navigation properties containing a nested $select, each suffixed with the parenthesized comma-separated list of properties selected (or expanded with a nested $select) from the related entities.

Example 22: resource URL and corresponding context URL

http://host/service/Employees(1)/Sales.Manager?
                   $expand=DirectReports($select=FirstName,LastName;$levels=4)

http://host/service/$metadata
       #Employees/Sales.Manager(DirectReports+(FirstName,LastName))/$entity

11 Collection of Entity References

Context URL template:

{context-url}#Collection($ref)

If a response is a collection of entity references, the context URL does not contain the type of the referenced entities.

Example 23: resource URL and corresponding context URL for a collection of entity references

http://host/service/Customers('ALFKI')/Orders/$ref

http://host/service/$metadata#Collection($ref)

12 Entity Reference

Context URL template:

{context-url}#$ref

If a response is a single entity reference, $ref is the context URL fragment.

Example 24: resource URL and corresponding context URL for a single entity reference

http://host/service/Orders(10643)/Customer/$ref

http://host/service/$metadata#$ref

13 Property Value

Context URL template:

{context-url}#{entity}/{property-path}{select-list}

If a response represents an individual property of an entity with a canonical URL, the context URL specifies the canonical URL of the entity and the path to the structural property of that entity. The path MUST include cast segments for properties defined on types derived from the expected type of the previous segment.

Example 25: resource URL and corresponding context URL

http://host/service/Customers(1)/Addresses

http://host/service/$metadata#Customers(1)/Addresses

14 Collection of Complex or Primitive Types

Context URL template:

{context-url}#Collection({type-name}){select-list}

If a response is a collection of complex types or primitive types that do not represent an individual property of an entity with a canonical URL, the context URL specifies the fully qualified type of the collection.

Example 26: resource URL and corresponding context URL

http://host/service/TopFiveHobbies()

http://host/service/$metadata#Collection(Edm.String)

15 Complex or Primitive Type

Context URL template:

{context-url}#{type-name}{select-list}

If a response is a complex type or primitive type that does not represent an individual property of an entity with a canonical URL, the context URL specifies the fully qualified type of the result.

Example 27: resource URL and corresponding context URL

http://host/service/MostPopularName()

http://host/service/$metadata#Edm.String

16 Operation Result

Context URL templates:

{context-url}#{entity-set}{/type-name}{select-list}

{context-url}#{entity-set}{/type-name}{select-list}/$entity

{context-url}#{entity}/{property-path}{select-list}

{context-url}#Collection({type-name}){select-list}

{context-url}#{type-name}{select-list}

If the response from an action or function is a collection of entities or a single entity that is a member of an entity set, the context URL identifies the entity set. If the response from an action or function is a property of a single entity, the context URL identifies the entity and property. Otherwise, the context URL identifies the type returned by the operation. The context URL will correspond to one of the former examples.

Example 28: resource URL and corresponding context URL

http://host/service/TopFiveCustomers{}

http://host/service/$metadata#Customers

17 Delta Response

Context URL template:

{context-url}#{entity-set}{/type-name}{select-list}/$delta

The context URL of a delta response is the same as the context URL of the root entity set, followed by /$delta.

Example 29: resource URL and corresponding context URL

http://host/service/Customers?$deltatoken=1234

http://host/service/$metadata#Customers/$delta

18 Item in a Delta Response

Context URL templates:

{context-url}#{entity-set}/$deletedEntity

{context-url}#{entity-set}/$link

{context-url}#{entity-set}/$deletedLink

In addition to new or changed entities which have the canonical context URL for an entity a delta response can contain deleted entities, new links, and deleted links. They are identified by the corresponding context URL fragment. {entity-set} corresponds to the set of the deleted entity, or source entity for an added or deleted link.

19 $all Response

Context URL template:

{context-url}#Collection(Edm.EntityType)

Responses to requests to the virtual collection $all  use the built-in abstract entity type. Each single entity in such a response has its individual context URL that identifies the entity set or singleton.

20 $crossjoin Response

Context URL template:

{context-url}#Collection(Edm.ComplexType)

Responses to requests to the virtual collections $crossjoin(...) use the built-in abstract complex type. Single instances in these responses do not have a context URL.

 

 

 

 

 

 

 

 

 

 

 

 

Refers:

http://www.odata.org/documentation/

https://www.cnblogs.com/1zhk/p/5356053.html