Software AG Products 10.11 | Using CentraSite | Asset Management | Managing Assets through CentraSite Business UI | OData Service Management | About OData Service Assets
 
About OData Service Assets
Open Data Protocol (OData) enables the creation of REST-based services, which allow resources to be exposed as endpoints and identified using the Uniform Resource Identifiers (URIs). In general, OData is represented by an abstract data model called Entity Data Model (EDM). This Entity Data Model allows Web clients to publish and edit REST services and their resources using simple HTTP messages.
OData leverages the principles of HTTP, REST and ATOM, and combines the simplicity of REST and SOAP metadata definitions to describe service interfaces, data models, and semantics.
The descriptions in this topic are based on a sample OData service, TripPinService.
Instructions throughout this guide use the term OData Services when referring to OData Service assets.
The Entity Data Model (EDM)
This section provides a high-level description of the EDM, which is the underlying abstract data model used by OData services.
An OData Service Metadata Document describes its data in EDM terms using an XML language. The remainder of this section provides a brief description of the Entity Data Model and defines how EDM constructs are mapped to the resources of the CentraSite OData model.
The following table lists the OData EDM components that are mapped to an OData service in CentraSite:
OData (EDM) Components
Description
Service
The simple OData Service which implements the Open Data Protocol (OData).
Schema
The Schema(s) exposed by the OData service. The schema in XML language describes the service’s data in EDM terms. For example:
<Schema xmlns="http://docs.oasis-open.org/odata/ns/edm”>
Namespace
The Namespace used by OData services when representing data in XML-based formats. The URI identifying the namespace is <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="services.odata.org.TripPin">
Version
The Version of the OData protocol required to consume the service. The supported OData protocol versions are 2.0 and 4.0. For example,
<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0">
EnumType
Enumeration Types (for example, PersonGender) represent a series of related values. Enumeration types expose the related values as members of the enumeration.
The following example shows a simple enum for our sample TripPinService:
<EnumType Name="PersonGender">
<Member Name="Male" Value="0"/>
<Member Name="Female" Value="1"/>
<Member Name="Unknown" Value="2"/>
</EnumType>
ComplexType
Complex Types are structured types (for example, City, Location, Airport Location and so on) consisting of a list of properties (for example, CountryRegion, Name, Address, and so on) but with no key, and thus can only exist as a property of a containing entity or as a temporary value.
The following example shows a simple complex type for our sample TripPinService:
<ComplexType Name="City">
<Property Name="CountryRegion" Type="Edm.String"
Nullable="false"/>
<Property Name="Name" Type="Edm.String"
Nullable="false"/>
<Property Name="Region" Type="Edm.String"
Nullable="false"/>
</ComplexType>
EntityType
Entity Types (for example, Person, Airline and so on) are structured records consisting of named and typed properties and key properties whose values (for example, UserName, AirlineCode and so on) uniquely identify one instance from another.
The following example shows a simple entity type for our sample TripPinService:
<EntityType Name="Person" OpenType="true">
<Key>
<PropertyRef Name="UserName"/>
</Key>
<Property Name="UserName" Type="Edm.String"
Nullable="false"/>
<Property Name="FirstName" Type="Edm.String"
Nullable="false"/>
<Property Name="LastName" Type="Edm.String"
Nullable="false"/>
<Property Name="Emails" Type="Collection
(Edm.String)"/>
</EntityType>
Property
The Property element allows the construction of structural types from a single value or a collection of values.
<Property Name="UserName" Type="Edm.String"
Nullable="false"/>
<Property Name="Emails" Type="Collection
(Edm.String)"/>
NavigationProperty
The Navigation Property allows navigation from an entity to related entities.
In the following example, the Person entity type has the navigation properties, for example, Friends, Trips, and Photo:
<EntityType Name="Person" OpenType="true">
...
<NavigationProperty Name="Friends" Type=
"Collection(services.odata.org.TripPin.Person)"/>
<NavigationProperty Name="Trips" Type=
"Collection(services.odata.org.TripPin.Trip)"
ContainsTarget="true"/>
<NavigationProperty Name="Photo" Type=
"services.odata.org.TripPin.Photo"/>
</EntityType>
EntityContainer
An Entity Container corresponds to a logical data store and contains zero or more entity sets and function imports.
A full example of an entity container is as follows:
<EntityContainer Name="DefaultContainer">
<EntitySet Name="Photos"
EntityType="services.odata.org.TripPin.Photo"/>
<EntitySet Name="People"
EntityType="services.odata.org.TripPin.Person"/>
<EntitySet Name="Airlines"
EntityType="services.odata.org.TripPin.Airline"/>
<FunctionImport Name="GetNearestAirport"
Function="services.odata.org.TripPin.GetNearestAirport"
<EntitySet="Airports"
IncludeInServiceDocument="true">
</FunctionImport>
</EntityContainer>
EntitySet
An Entity Set element represents a single entity or a collection of entities of a specific entity type in the data model.
For example, the entity set identified by the URI http://services.odata.org/V4/TripPinService/People('scottketchum')/Friends or the collection of entities identified by the "Friends" navigation property in http://services.odata.org/V4/TripPinService/People('scottketchum')/Friends('russellwhyte')/Trips identifies a feed of entries exposed by the OData service.
Singleton
Singletons are single entities which are accessed as children of the entity container.
A simple example of a singleton is as follows:
<Singleton Name="Me" Type="services.odata.
org.TripPin.Person">
<NavigationPropertyBinding Path="Friends"
Target="People"/>
<NavigationPropertyBinding Path="Photo"
Target="Photos"/>
</Singleton>
FunctionImport
The Function Import element represents a Function in an entity model.
A simple example of a Function Import is as follows:
<FunctionImport Name="GetNearestAirport"
Function="services.odata.org.TripPin.GetNearestAirport"
EntitySet="Airports" IncludeInServiceDocument="true">
<Annotation Term="Org.OData.Core.V1.ResourcePath"
String="services.odata.org.TripPin.GetNearestAirport"/>
</FunctionImport>
Function IsBound
The Function IsBound element denotes if the function is bound to a specific entity type in an entity model.
A simple example of a Function IsBound is as follows:
<Function Name="GetFavoriteAirline"
IsBound="true"
EntitySetPath="person/Trips/PlanItems/
Services.odata.org.TripPin.Flight/Airline"
IsComposable="true">
<Parameter Name="person"
Type="services.odata.org.TripPin.Person"
Nullable="false"/>
<ReturnType Type=
"services.odata.org.TripPin.Airline"
Nullable="false"/>
</Function>
Function Parameter
The Function Parameter element represents a parameter to the function.
The following example demonstrates a Function that contains two parameters:
<Function Name="GetNearestAirport"
IsComposable="true">
<Parameter Name="lat" Type="Edm.Double"
Nullable="false"/>
<Parameter Name="lon" Type="Edm.Double"
Nullable="false"/>
<ReturnType Type="services.odata.org.TripPin.Airport"
Nullable="false"/>
</Function>
ActionImport
The Action Import element represents an Action in an entity model.
A simple example of an Action Import is as follows:
<ActionImport Name="ResetDataSource"
Action="services.odata.org.TripPin.ResetDataSource"/>
Action IsBound
The Action IsBound element denotes if the action is bound to a specific entity type in an entity model.
A simple example of an Action IsBound is as follows:
<Action Name="ShareTrip" IsBound="true">
<Parameter Name="person"
Type="services.odata.org.TripPin.Person"
Nullable="false"/>
<Parameter Name="userName" Type="Edm.String"
Nullable="false"/>
<Parameter Name="tripId" Type="Edm.Int32"
Nullable="false"/>
</Action>
Metadata for OData Services
An OData service is best described using two types of OData Service Metadata documents:
*Service Document - The service document serves as the entry point for navigating to the OData service resources. This document lists all of the resources, entity sets, functions and singletons. The service document is typically available at the Base URL in the ATOM or JSON format. For example, this URI http://services.odata.org/V4/TripPinService identifies the service document for a sample OData service.
*Metadata Document - The metadata document describes the Entity Data Model (that is, the structure and organization of the OData service resources) exposed as HTTP endpoints by that particular service. This document describes the entity types, entity sets, functions and actions. For example, this URI http://services.odata.org/V4/TripPinService/$metadata identifies the metadata document for a sample OData service.
The CentraSite OData Model
The CentraSite OData Model provides the resource-oriented interface for an OData service ensuring that the representation of OData services is in-line with the representation of REST services.
An OData service is represented in CentraSite by an asset instance of the “OData Service” type, which is one of the predefined types installed with CentraSite. An OData service instance in CentraSite precisely describes a collection of OData Resources that represent the resource structure of an OData EDM.
This section describes how the EDM objects and properties (as described in the Service Document URL or the Metadata Document) are represented in the CentraSite OData model.
Note:
CentraSite supports OData versions 2.0 and 4.0.
EDMX to CentraSite OData Service Mappings
The following table lists the corresponding representations of OData Entity Data Model in the Resource Oriented Architecture (ROA) of the Business UI.
This EDM Component…
Is Referenced Using the OData Service Field…
Service
OData Service
The OData service is represented by an asset instance of the type OData Service in the CentraSite registry.
Version
Version
The OData version (for example, 2.0 or 4.0) is represented by the Version field in the OData API's Technical Details profile.
EntityType
Entity Types
The OData entity type (for example, Person) is represented by the Entity Types field in the Entity Sets. The Entity Types field is contained in the OData Resources profile.
NavigationProperty
Navigation Properties
The OData navigation property (for example, Friends, Trips, Photo) is represented as an OData Resource and denoted as OData Navigation Properties inside the OData Resources profile.
EntityContainer
OData Service
The OData entity container (for example, DefaultContainer) is represented by a collection of Attributes which hold data that is specific to the OData service.
EntitySet
Entity Sets
The OData entity set (for example, photos, people, airlines and so on) is represented as an OData Resource and denoted as OData Entity Sets inside the OData Resources profile.
Singleton
Singletons
The OData singleton (for example, Me) is represented as an OData Resource and denoted as OData Singletons inside the OData Resources profile.
FunctionImport
Function Imports
The OData function import (for example, GetNearestAirport) is represented as an OData Resource and denoted as OData Function Imports inside the OData Resources profile.
Function Parameter
Resource Parameters
The OData function parameter or action parameter (for example, person, trip) is represented as an OData Parameter and denoted as OData Parameter of the type Path inside the OData Resources profile.
ActionImport
Action Imports
The OData action import (for example, ResetDataSource) is represented as an OData Resource and denoted as OData Action Imports inside the OData Resources profile.
The EDM components currently not supported in CentraSite are as follows:
*Schema
*Namespace
*EnumType
*ComplexType
*Property
*Function IsBound
*Action IsBound
Registry and Repository Entries for an OData Service
The OData components are represented in CentraSite by a set of related entries in the registry and in the repository. When an OData service is imported, the appropriate entries are created. Some of the entries are visible in the detail pages of the OData service asset; others are not displayed in the detail pages but are displayed when you use the asset navigator feature.
Supported HTTP Methods for OData Resources
The following table lists the HTTP methods supported for OData Resources. Not all of the HTTP methods are supported for an OData Resource.
OData Resource
Supported HTTP Methods
Entity Sets Resource (collection)
*GET
*POST
Entity Sets Resource (single)
*GET
*PUT
*PATCH
*DELETE
Singletons Resource
*GET
*PUT
*PATCH
Function Imports Resource
*GET
Action Imports Resource
*POST
Navigation Properties Resource (collection)
*GET
*POST
Navigation Properties Resource (single)
*GET
*PUT
*PATCH
*DELETE
Sample OData Resource URLs
*Resource URL: http://services.odata.org/V4/TripPinService/People('scottketchum')/Friends
Description: To fetch the friends of 'scottketchum'.
*Resource URL: http://services.odata.org/V4/TripPinService/People('scottketchum')/Trips
Description: To fetch the details on trips of 'scottketchum'.
*Resource URL: http://services.odata.org/V4/TripPinService/People('scottketchum')/Friends('russellwhyte')/Trips
Description: To find out if 'russellwhyte' is a friend of 'scottketchum' and fetch the details of his trips.
*Resource URL: http://services.odata.org/V4/TripPinService/GetNearestAirport(lat = 33, lon = -118)
Description: To find the nearest Airport.
*Resource URL: http://services.odata.org/V4/TripPinService/People('russellwhyte')/​Trips(0)/Microsoft.OData.SampleService.Models.TripPin.GetInvolvedPeople
Description: To find involved people for a trip (Calling a bound function requires a fully qualified function name).