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