Windows Azure Media Services API, a case study of OData protocol

Recently, I had been looking at the REST end point of Windows Azure Media Services (abbreviated to media services in the following paragraphs). The reference site is located here (https://msdn.microsoft.com/en-us/library/windowsazure/hh973617.aspx ). The design of the REST endpoints of Windows Azure Media Services is interesting because first it is a real service, and second the requirements of it is complicated, third, some of the usage of the OData may be of generic interests of web service design. 

Let's start from the positive aspects of OData. OData protocol centers around the concept of entity, all the OData libraries provide CRUD operation for free. For media services, Asset, AccessPolicy's REST endpoint implementation clearly benefit from it. Via some simple configuration, media services enables customers to perform create, list, retrieve, delete and update of those entities. In deed, OData provides some convenience of developing CRUD based operation on entities. 

The complications came around when the entity have multiple states or there are interactions between entities. OData protocol doesn't provide a standard way to model the multiple states of the entity. For media services, Job or Task entity can have mutliple states. They can be in waiting, running, error, completed, or stopped mode. It is possible to use the UPDATE method to alter the state of them, but that is a kind of counter intuitive. For example, the validation of the state change may not be easy to model using a single UPDATE operation. 

The second scenario to show the insufficiency of the current OData protocol is the interaction between the entities. For media services, Job and Task have an hierarchy relationship. A Job can have multiple Tasks. A Task can use ContentKeys. When a Job is deleted, all the tasks of the specified Job are deleted, and all the Content Key of each task are also deleted. Specifically, Configuration ContentKeys can be created using ContentKey CREATE operator, but can only be deleted by deleting the Job which uses it. We have to do this on server side, mostly because OData protocol does not provide a strong query capability to operate the entities beyond simple CRUD operation. 

Overall, OData protocol introduced some internal structure of the largely un-organized REST based web service, at the same time, it also makes writing a Web Services' client extremely expensive if they do use an existing OData client library.