OData

The OData service broker supports OData’s Service Operations. (Service Operations should not be confused with Actions and Functions, which are similar in nature. The broker does not expose Actions and Functions). Service Operations appear in the Operations folder. Each Service Operation is represented by a Service Object. A Service Operation Service Object exposes either a Load or an Execute method, or the three list methods (List, List To Serialized Item, and Read To Serialized Item).

Service Operation Service Objects discover all of the input properties, the return type, the function name, and required properties. They also handle all of the query string or body parameter construction.

A Service Operation can be bound to a particular entity or entity set. If a Service Operation is bound to a particular entity, the Service Operation allows you to specify that entity by exposing the primary keys of the entity as input properties.

The default HTTP method type for a Service Operation is POST. This default is used when the service does not specify a method type for a Service Operation. To override this default, the Default Http Method For Operations service key setting is provided in the service instance configuration. The two valid values are GET and POST. Any other values will cause the broker to default back to POST.

Service Operations have a naming convention consisting of:
MethodName (dataType + parameter , dataType + parameter)
So a service operation called MyServiceOperation with a text parameter of myString and a number parameter of myNumber would have the service object name:
MyServiceOperation(String myString, Int32 myNumber)

Due to ambiguity issues that can be present in OData implementations, filtering will work, but it will not be executed in the OData service by default. All filtering on service operations is done in the SmartObject framework unless the HandleServiceOperationsFilters config setting is set to True:

The screenshot below is a sample of the Service Object representation of OData.Org’s sample service operations:

The GetProductsByRating service operation’s List method on the OData.Org sample service:

When a relationships exists between entities, the service broker exposes these relationships on the list methods, if the Add Navigation Properties To List Methods service key setting is True.

One-One/Many (1:1-M)

In this example, Product has a 1:M relationship to Supplier. Each Product has one Supplier and a Supplier can have many Products. On the List method for the Product you see the Supplier/ID, which allows you to return products from a particular supplier. If you wanted to return all the products from a particular supplier you would pass in the supplier ID:

Many-One/Many-Many (M:M or M:1)

A Product has a M:M relationship to Category. Each Product can be in multiple Categories and each Category can have multiple Products.
For example, to get all the categories a product is in, pass in the product ID to the Category List method:

To get all the products in a category, use the Product List method and pass in the Category ID:

The OData broker handles complex SmartObject filtering. The SmartObject filter is translated to the corresponding URL to improve performance. For example, if you wanted to get all the Products where the Name starts with B and the Rating is greater than 1 you would use the following filter:

The corresponding URL looks like this:
http://services.odata.org/V3/(S(omdt3ebrzqrvcyfv1gsi5noq))/OData/OData.svc/Products()?$expand=Supplier,ProductDetail&$filter=startswith(Name, 'B') eq true and Rating gt 1

If the SmartObject framework filter does not expose the functionality necessary for your query, an additional parameter can be used to create custom queries. To turn this input parameter on, the set the Add Query Options Property To Methods service key to True. Once you to, the parameter appears on the Load, List, ListToSerializedItem, and ReadToSerializedItem methods.

Then custom queries like this one becomes possible:
http://services.odata.org/OData/OData.svc/Products?$top=5&$skip=2

This would be constructed in the SmartObject Service Tester like the following example:

The Query Options input property can be used in conjunction with the SmartObject filter safely. The OData service broker handles combining the two parameter groups together.

The Query Options supported are

• $filter
• $skip
• $top
• $take
• $orderby
• $select

Query options which return values other than those described on the service object method will not work.

Calling the Create or Delete methods does not create or delete Links to other entities. Instead use the Create Link and Delete Link methods to manage links between entities. These methods only appear on Service Objects in the Entities folder that have either one-to-many or many-to-many relationships with another entity. Many-to-One relationships must be set up through the other side of the relationship. 
For example:
A Company has many Employees, but an Employee has only one Company.
Only the ‘Company’ Service Object exposes the Create Link and Delete Link methods.

An example of the Create Link and Delete Link methods on the Product entity from odata.org’s V3 service.
(The Product entity has a many-to-many relationship with the Category entity)

If an entity contains a complex type that is not an entity, then a Service Object is created for the complex type but without the CRUD methods. All complex types in service brokers are handled using serialization and deserialization, For more information please read the Serialization/Deserialization topic.

OData Services have the option to expose files through resource streams. Media resources are exposed through the /$value route on the end of an entity’s URL. The URL to retrieve a media resource from an entity called ‘MediaEntity’ would be: http://myservice.com/OData/OData.svc/MediaEntity(1)/$value.

Named resources are exposed in a similar fashion but specify the property they apply to. The URL to reach the named resource on an entity with a property named ‘Photo’ would be: http://myservice.com/OData/OData.svc/NamedResourceExample(1)/Photo/$value.

If an entity exposes a media or named resource, then it also exposes two methods: Load Without Content and List Without Content. These methods only return the basic properties and the URL pointing to the media or named resource. The standard Load and List methods return URLs and the full media or named resource files.

Example of the Hyperlinks on a media resource stream’s List Without Content method:

Media and Named Resource Streams are supported in the OData Broker through FileProperties. The FileProperties are only exposed on the basic CRUD methods. List methods do not retrieve resource streams. Instead, list methods expose the hyperlinks to the URLs of the resource streams that can be used in your applications or forms.

Media and Named Resource Streams also expose additional properties to support the main file property. These properties are the Media/Named Resource Stream Path and the Resource Stream MIME Type properties.

The MIME Type property is used to indicate the MIMEType of the file being saved through the ContentType header on the HTTP request to the service.  If the MIMEType property is populated, its value overrides the file’s extension and any other internal processing the broker might use to figure out the MIMEType.

The Path property is used to set the Slug header on the HTTP request. If this header is left empty, the Slug header is not added to the HTTP request. The Slug header is often used in OData services to indicate where the resource stream should be saved on the server. There is no processing on the value in this property so if the service requires the Slug header to be populated for reasons other than path specification, this property can be used.

An example of a Media Resource Stream being retrieved:

An example of the Media Resource properties on an update method:

An example of a Named Resource Stream for a Photo property being retrieved:

An example of the Named Resource properties for the Photo property on the Create method:

If the EntityContainers name matches part of the service namespace a conflict occurs when registering the service causing an error. An example of the type of error is shown below:

The conflict can be seen in the service metadata XML. In the following example TextAnalytics is the EntityContainer Name and it is also part of the Namespace. TextAnalytics.FrontEndService

There are two ways to resolve the issue:

1. Change the system name when registering the service to match the name causing the conflict.
   
2. Download the XML metadata file, edit the EntityContainer Name to any other name, save the file and then change the metadata URL to point to your updated XML file.