Apigee API Management - Best Practices - Naming Conventions



Many of the big projects tend to have different teams working on different features of the product. Same is the case with API management in APIGEE. In multi-team project or even in a single team but with different developers it is difficult to have a uniform naming standard unless specifically defined.
Most of the developers follow their own naming standards which they are comfortable with, like camel casing or underscores or hyphens etc.
In APIGEE we have many artefacts that are used to configure the runtime of the proxies. Here is a concise list of artefacts and the naming best practices used for them.

Naming conventions best practices:

Proxy


  1. Name your proxies with the entity they deal with or the function they carry out.
    • Entity examples : customers, accounts, bookings
  2. If you have different versions then include the version number as well 
    • customers-v1, customers-v2

Policies

  1. Use a two/three letter acronym for policy as a prefix.
  2. Name policy as per their functional behaviour.
  3. Policy name should match with the XML file name
  4. Display names should accurately describe policy's function
    • Examples: AM-SetSOAPHeaders, SC-GetTargetServerInfo, KVM-GetCustomersConfigs etc.

Products



  1. Prefix the environment to the product like {env}-{product}. 
    • dev-goldkeycustomers, sand-premium etc.

Applications

  1. This is the naming conventions for developer applications.
  2. Use a format like {company}-{project}-{apiproxy}-{env}
    • Example : google-android-pushv2-qua

Variables

  1. Define variables with a dot notation
  2. Group related variables into a hierarchy.
    •  "target.username" , "target.password", "target.basepath" etc.
  3. Use different naming for general purpose flow variables and configuration variables.
    • Example: Use "flow.mycompany.var1" for flow variables
    • "config.mycompany.var2" for KVM configured variables

Cache Resources

  1. Use naming like {api}-{version}-{name of cache}
    • Example: customers-v2-countriescache

Key Value Maps

  1. Use naming like {api}-{version}-{name of KVM}
    • Example : customers-v2-saptargetconfig
  2. For global configurations to be used by multiple APIs
    • global-{version}-{descriptive-name}

Javascript, Java and Python Callouts

  1. Name script/callout policy and the script file or jar the same.
  2. Use proper extensions for resource files, .js for javascript and .py for python, and .jar for Java jar files.

Resource Path

  1. Paths should be a resource not action-centric. /v1/accountAPI/entries is the base path for customer operations. Verbs are used to differentiate actions whenever possible rather than appending information to the path.
  2. Avoid using non-alpha characters and capitals in paths.
  3. Resources should always be represented as plurals.


These are the namings that I personally prefer, but if you any more good thing to share do comment.