Skip to Content

This post describes the importance of having some kind of name convention when creating an oData service, specially in SAP Gateway. All conventions suggested here are based on my personal thoughts.

Have you ever worked with oData services which had bad or no naming convention at all? This is usually an indication that the back end implementation was done with the same level of care.

So, I would like to share what I believe is a good naming convention for every piece of a oData Service created using SAP Gateway.

oData Terms

oData term Meaning Used in UI5 code? General Suggestion Examples:
Entity Type A type that can be reused in many Entity Sets No

Use a singular noun

Camelcase

Material

SalesDocument

SalesDocumentItem

Employee

Salesperson

Entity Set The most important part of your service. Data is retrieved via them Yes

Use a plural noun

Camelcase

Given you have a single entity set for a given entity type:

  • Materials
  • SalesDocuments
  • SalesDocumentItems

Given you reuse an entity type multiple times:

  • Employees / Contractors (Entity type Employee)
  • FinishedGoods / RawMaterial (Entity type Material)
Association

Link between two entity types

Contain details about cardinality

No Parent Entity Type Name + [separator] + Child Entity Type Name

SalesDocument_SalesDocumentItem

Employee_Employee

SalesDocumentItem_Material

Association Set Link between two entity sets No Parent Entity Set Name + [separator] + Child Entity Set Name

SalesDocuments_SalesDocumentItems

Employees_Employees

SalesDocumentItems_Materials

Complex Type A type that can be reused and which don’t need to have a key No Same as Entity Type Same as Entity Type
Function Import Functionality which cannot be catagorized using CRUD-Q as Entity Sets. Yes

Use verbs at the beginning (as usually happens in SOAP services).

Make it a sentense

CheckUserAuthorization

GetFioriDynamicTileData

ApprovePurchaseOrder

Function Import Parameter URL parameter of function imports Yes

Use nouns

lower case

id

name

code

Property Compared with a ‘column’ in relational database modeling Yes

Use the same rule for all properties among all Entity Types and Complex Types

Camelcase

Singular

Meaningful

Good

  • Id
  • Name
  • CompanyName
  • CostCenterGroupId
  • CostCenterGroudName

Bad

  • Bukrs
  • Werks
  • Uname
  • Vbeln
Navigation Property

Compared with a ‘foreign key’ in relational database modeling

Are linked with Associations

Yes

Use a prefix (i.e. To) to distinguish them from regular properties.

Use singular noun when linked with an association which has a 1:1 relationship

Use plural noun when linked with an association which has a 1:n relationship

ToFullName (1:1)

ToCustomer (1:1)

ToCustomers (1:n)

ToItems (1:n)

 

SEGW

1) Project Name

Make it as short as possible. Up to 13 characteres if you want to have your gateway project with the same name of your UI5 app (BSP). If not, make it short enough so that DPC and MPC classes have names matching SEGW project (30 characteres considering prefix ZCL and suffix _DPC_EXT)

2) Description

Give the same name of the Fiori App (if your project is for Fiori) which will consume this service. (by the way, do not reuse the same oData service among manu apps).

3) Service Generation

When using function modules inside your project to use what is called service generation, name your function module with the exact entity and operation which will be mapped inside SEGW >> Service Implementation. Examples are:

  • Z_MYAPP_CUSTOMERS_Q (Query on Customers EntitySet)
  • Z_MYAPP_CUSTOMERS_R (Read on Customers EntitySet)
  • Z_MYAPP_SALES_ORDERS_C (Create on SalesOrders EntitySet)
  • Z_MYAPP_SALES_ORDERS_U (Update on SalesOrders EntitySet)
  • Z_MYAPP_SALES_ORDERS_D (Delete on SalesOrders EntitySet)

Gateway Configuration

System alias

Do not use the system ID to give your system alias a name. The only purpose of the system alias is rename the RFC destination so your DEV/QAS/PRD environments have all the same routing configuration.

Use names like: “ECC” , “S4”, “CRM” or “SOLMAN”

What does help you?

I hope your liked such conventions. Do you already use any? Please share your opinion below!

To report this post you need to login first.

5 Comments

You must be Logged on to comment or reply to a post.

  1. Mike Doyle

    A very nice blog, Fabio.  Thanks for sharing your good practices.  If you don’t mind me suggesting you could make your examples better match your rules.  For example, you say that entity types should be named so that they could be used in multiple entity sets (good point), yet each entity type is only used in one entity set.  Rather than Employee/Employees you could use Person/Employees, Contractors.

    Also, shouldn’t your navigation properties be ToCustomer (1:1) and ToCustomers(1:n) ?

    Why do you give your function import parameters lowercase names?

    I wholeheartedly agree that a system alias should be generic e.g. ECC not DEV.  I’m not sure it’s widely known that if your alias is the same in each environment you can add the assignment to a customising request and hence move it through the landscape.  That saves a manual step that requires the client to be opened.

    I would add that Properties should never contain SAP-specific fieldnames like bukrs or kunnr as these might not mean much to a front-end developer.

     

    (1) 
    1. Fabio Pagoti Post author

      Thank you Mike Doyle! 

      I agree. I have just added all suggestions to the blog post. (yes, the navigation property example was wrong).

      I wholeheartedly agree that a system alias should be generic e.g. ECC not DEV.  I’m not sure it’s widely known that if your alias is the same in each environment you can add the assignment to a customising request and hence move it through the landscape.  That saves a manual step that requires the client to be opened.

      Based on my experience almost no one does that. The part which does this is probably not aware why. (Maybe this could be a good tip for a different blog post!)

      Finally, I say that SAP-specific fieldnames are not meaningful even for ABAP developers. Just a few of them are ( < 1% ).

      (0) 
  2. Graham Robinson

    Thanks for this blog Fabio,

    you have triggered a wider discussion than I expected from this – well done.

    Your naming conventions match those I use almost 100% – after all it just makes sense when building an API that you should name things what they are. 😉

    The only place where we diverge is the naming of navigation properties. You like to use the ‘To’ prefix whereas I don’t see a need to use naming to distinguish between entity properties and navigation properties as they are well separated in both the metadata and the entity contents.

    I also hate Hungarian Notation. 😉

    Good stuff!

    Cheers

    Graham Robbo

    (1) 
  3. John Patterson

    Hey Fabio et al,

    Gateway how hard can it be, its just ABAP 😉

    Just a thought, why not create a Gateway Style guide in Github?

    That way people can fork it, review, push changes, open issues and generally discuss what is good practice.

    Cheers

    JSP

     

     

     

     

     

    (0) 
  4. Phil Cooley

    Nice blog Fabio, in the projects I have been involved in we always created the service in SEGW as ZGWS…….followed usually by the module the Odata service related to. For Purchase order updates it would be ZGWS_MM_PURCHORD_UPD – something to this effect. I quite liked the ZGWS because you could quickly find all of the customised gateway services you have defined. I get that you could also find them with Z* but I thought it was a good convention anyway.

    The other convention was to prefix VH (for value help) for entity sets that simply provided a value set. This was a nice way of also identifying those entity sets that were value helps and not values of data from objects.

    (0) 

Leave a Reply