Collections and complex types
This is part of the ongoing blog about frequently asked questions on OData
This week we will cover how do I discover what services are available, what collections are in each service and how to I access each entity in each service?
How do I get a list of services?
Currently there is no OData approved standard for obtaining a list of service documents from a particular server, however there is ongoing work inside the OData specification team to build this functionality. SAP being at the forefront have already implemented this in theirs servers and have called it the Service Catalog.
For now the developer is expected to be supplied a URL that contains the service document, at least until OData 4 where the situation on service catalogs should be clarified.
How do I get a list of collections?
The consumer/developer will be supplied a URL and that URL will point to a service document that will list the collections available for consumption by them (obviously subject to their authorisation level)
For example to access Netflix expose an OData service document that lists the various collections that are exposed by them for consumers to consume.
http://odata.netflix.com/v2/Catalog/ lists all the services that netflix allows developers to query against.
This is termed the service document or service root and simply exposes the collections. A more detailed version of the these collections can be obtained by querying for the metadata. http://odata.netflix.com/v2/Catalog/$metadata lists all the metadata available for consumption. Looking at the entity container element (normally found towards the end of the document) there will be a number of EntitySets which amount to the collections exposed by the service.
How do I get an individual entity?
An individual entity is accessed using the service url + the collection name + the key for the entity.
For example if we were to retrieve a movie from netflix we would use the following URL:
http://odata.netflix.com/v2/Catalog/Titles(’13aly’) which will return the entity data for the “Red Hot Chili Peppers: Funky Monks” film released in 1991.
Remember that each entity has a key associated with it, so each entity is uniquely accessible within the collection and conversly an entity may not exist without a unique key though the key may be a collection of properties so compound keys are also supported and appear in the form
http://odata.service/collection(key1=’value‘, key2=’value’), though its not possible to show an example here since there are no compound keys in the netflix OData feed.
How do I get complex types within an entity?
It is also possible to drill down and only return an individual property (or complex type) of an entity by appending the property name to the entity URL and even drill down into those complex property types still further till only a scalar type is left.
For example http://odata.netflix.com/v2/Catalog/Titles(’13aly’)/ReleaseYear will return just the release year of “Red Hot Chili Peppers: Funky Monks”. This use case just covers returning an individual property and not a number of properties, later on we will see how to use the $select system query option.
This type of query will return properly formatted xml document or JSON response with the value in it. If just the value is required then appending a $value to the URL will return just the native data to the caller if it is present. If the value is missing in the backend then a 404 error will be returned.
For example the above URL returns:
Where as the URL with $value appended to it:
http://odata.netflix.com/v2/Catalog/Titles(’13aly’)/ReleaseYear/$value returns just 1991 by itself
Next entry we will cover changing the format the data is returned in and how to restrict the amount of data returned through the use of System Query options….