Show TOC

Creating High-Quality OData ServicesLocate this document in the navigation structure

Use

To improve the quality of your OData services developed with SAP Gateway, consider the following recommendations, which describe how to improve the service representation from a consumer perspective.

More Information

For more general information about OData guidelines, see OData Best Practices.

Dos and Don'ts

Recommendations for Model Provision (Metadata)

Level

Don't

Do

Schema

 

Do add a document element (mandatory for function imports).

Entity Type

Don't use technical names or field names of underlying data sources (such as BAPI, function modules).

Do use readable and understandable terms.

Don't use uppercase or snake case (SALES_CONTACT).

Do use upper camel case (SalesContact).

Don't use the same name for a property or navigation property and its enclosing entity type.

Do add document element at entity type level.

Property (Naming)

Don't use uppercase or snake case (CUSTOMER_NAME) or a combination of both for property names.

Do use upper camel case (CustomerName).

Don't use technical names or field names of underlying data sources (such as BAPI, function modules).

Do use readable and understandable terms.

Property (Typing)

Don't use edm:string for everything.

Do use appropriate (specific) property types.

Property (SAP Annotations)

Don't use unit of measure or currency code properties without reference.

Do maintain SAP annotations appropriately. Use sap:label at property level (mandatory). All other annotations must be maintained if they differ from default value.

Do set SAP semantic to unit of measure or currency code for unit of measure and currency code properties.

Do ensure that at least one property with the annotation filterable=true exists if the corresponding entity set has the annotation requires-filter=true.

Do ensure that at least one property should have the annotation filterable=true if the corresponding entity set has the annotation addressable=true.

Property (Feed Customization)

 

Do set appropriate feed customization for atom:title.

Do set appropriate feed customization atom:updated.

Do ensure that the property type does match the target path FC_TargetPath.

Do ensure the following if the hasstream attribute is set to true and there is a property annotated with FC_TargetPath='content/@src":

  • Property has type string (as it is intended to contain the URI of the corresponding media resource for each entry of this entity type).

  • Exactly one other string property is annotated with FC_TargetPath="content/@type" (indicating that this property contains the mime type of the media resource).

Property (Others)

Don't use large binaries in an OData stream.

Do use media resources and media link entries.

Don't use a large number of properties.

Do keep the number of properties as low as necessary. Consider using complex types to structure your properties.

Do validate your terms again dictionary (for example, SAPTerm, Babylon).

Navigation Property (Naming)

Don't use HTTP method name (such as GET) as prefix, suffix or infix.

Do use names that reflect the navigation end points as well as the cardinality.

Association (Naming)

 

Do use names that reflect the corresponding association cardinality (Product_Supplier_Supplier_Products).

Entity Set (Naming)

 

Do use plural term of the entity type for entity sets (Products).

Entity Set (SAP Annotations)

 

Do set the addressable annotation at entity set level to false so user does not query entity set directly.

Do ensure that at least one property with the annotation requires-filter exists or at least one property without the annotation requires-filter exists if entity set has the annotation requires-filter=true.

Function Import

Don't use HTTP method name (such as GET as prefix, suffix or infix). For example, GetProductByRating.

Do use ProductsByRating.

Do use appropriate HTTP method. A GET method must have a return type. Post should have parameters.

Recommendations for Data Provision (Runtime)

Level

Don't

Do

Entry

Don't return error messages that are not user friendly, that is, that are not easily understandable and clear.

Do ensure the src attribute of the content element points to a valid URI if the corresponding entity type has attribute m:HasStream=true.

Don't use empty values for DateTime such as 0000:00:00T00:00:00 or T00:00:00 since this leads to problems when consuming the feed in SharePoint.

Do ensure that all collections with sap:addressable=true have appropriate returns.

Do ensure the implemented methods do not have side effects. For example, a Get method must not change or create any objects in the system.

Do use exception class /IWBEP/CX_MGW_BUSI_EXCEPTION for errors related to business logic.

Do catch exceptions from business logic and, if needed, use your own error messages.

Do fill DateTime values appropriately.

Do implement factory pattern based on entity set name to distinguish between requested sets if multiple entity set definitions exist for a single entity type.

Recommendations for OData Channel

If you adopt an outside-in approach (that is you want to base a service on an existing metadata file), we propose you use the Import Model function to generate a basic implementation. Using the Import Model function enables you to use common structures and a predefined programming pattern and style.

Level

Don't

Do

Service Endpoint

Don't use sap-client in the URI of service endpoints.

Do activate the service for the appropriate sap-client.

Do use Compatibility Mode for SP2, but only if it is explicitly required for your project.

Entity Type

Property

Complex Type

Don't use data element CHAR30 for everything.

Do choose appropriate DDIC elements like data elements or structures for data binding.

Entity Type

Complex Type

Don't reuse existing structures with a high number of fields if only a few of them are used in the data provider class.

Do use appropriate DDIC structures with a limited number of properties.

Property

 

Do maintain the field labels of your data elements appropriately. The medium field label is used as sap:label by default. A meaningful label improves the usability of the consuming UI when used as a column header, for example.