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.
For more general information about OData guidelines, see OData Best Practices.
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 (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. |