Apigee naming conventions
API conventions are outlined in the API convention document, offering a set of standard practices. However, it's important to note that Apigee also has specific conventions for objects such as policies, flows, and more, which are detailed in this chapter.
In this document, we will use the following table structure to denote the significance of an element. "Must" denotes that the element is mandatory; "Could" denotes it's optional and blank space denotes that the element is not required.
| Internal | Private | Partner | Public | Alternative |
|---|---|---|---|---|
| Must | Could |
Naming convention for API policies
In Apigee, policy names follow a specific naming convention. They are written in lowerCamelCase, and before the policy name, you should include an abbreviation that signifies the policy type.
Let's clarify how to name policies in Apigee. There are two naming conventions:
For 'Normal' policies
Convention: Combine the policy type with an underscore (_) and use lowerCamelCase for the policy name.
Examples
- ML_messageLogging
- VAK_verifyApikey
- Q_imposeQuota
For shared flow or service callout policies
Convention: Combine the policy type with an underscore (_) and add (sharedFlow/request verb) before the object of the flow, all in lowerCamelCase.
Examples
- FC_sharedFlowPreflow
- SC_POSTGenerateToken
These naming conventions help maintain consistency in naming your policies in Apigee.
This applies to both the “DisplayName” and the “name” of the policy.
| Internal | Private | Partner | Public | Alternative |
|---|---|---|---|---|
| Must | Must | Must | Must |
Naming convention for shared flows and flow hooks
When you encounter a situation where a set of policies needs to be utilized across multiple APIs, create 'shared flow.' There are two types of shared flows:
- 'General shared flows' are intended for use in all APIs, except for a few specific cases.
- 'Specific shared flows' are tailored for particular use cases, such as APIs with a specific backend.
To implement a shared flow, you use a 'flow hook' to attach it. This ensures that the shared flow is executed consistently for all API proxies deployed in a particular environment. Please adhere to the following conventions:
General shared flows
Convention: Use "Shared" followed by a verb and an object/flow name, and then the version.
Examples
- Shared_PreFlow-v1
- Shared_LoggingResponseTimes-v1
- Specific Shared Flows:
Convention: Start with "System," followed by a verb and an object/flow name, and then the version.
Examples
- System_BE1_AuthorizationHeaders-v1
- System_BE2_RemovePathSuffix-v1
Flowhooks
Convention: Begin with "Flowhook," followed by a verb and an object/flow name, and then the version.
Examples
- Flowhook_BE1_AuthorizationHeaders-v1
- Flowhook_BE2_RemovePathSuffix-v1
Naming convention for products
Products consist of one or more APIs. Product names are shown in the developer portal and should not reveal backend details. We've adopted a simple naming format:
For instance, the "Addresses-10000" product might include four API paths, like creating, updating, getting, and deleting addresses. This product has a specified quota of 10,000. We understand that there can be different addresses or labels from various backends. This naming is more of a general rule. However, if there are distinct types of addresses, such as delivery or customer addresses, you can add that to the product name, like "DeliveryAddresses-5000."
Regarding the product description, if it's designed for a specific customer group, you can mention it. If the group is diverse, you can skip it. Additionally, briefly describe what the product does, for example, "Searching for Dutch addresses" or "Handling customer data functions."
**Convention **
Subject/process (plural) + Quota
Examples
- Addresses-5000
- Customers-1000
- Labels-10000
- DeliveryAddresses-5000
| Internal | Private | Partner | Public | Alternative |
|---|---|---|---|---|
| Must | Must | Must | Must |
Naming convention for specifications
When publishing a product on the developer portal, it's essential to create a snapshot of the product's specification. To maintain simplicity, the specification published in the portal should have the same name as the product it pertains to. Additionally, you have the option to generate an API from a specification. In this scenario, you should name the specification after the API itself. When preparing to publish a product, you have two potential scenarios to consider:
- If the API is part of a larger product that includes multiple APIs, you should create the specification for the entire product. Be sure to specify the base path as "/", and give it the same name as the product.
- If the API has a one-to-one relationship with the product, you should either rename the specification or upload it again using the product's name.
When developers register through the developer portal, they have the freedom to create their own developer app with a name of their choosing. We do not enforce a specific naming convention for developer apps due to this flexibility. However, it is recommended that developers create a new developer app for each new consuming application, ideally incorporating the name of the consuming application for clarity.
| Internal | Private | Partner | Public | Alternative |
|---|---|---|---|---|
| Could | Must | Must |
Naming convention for developer applications
| Internal | Private | Partner | Public | Alternative |
|---|---|---|---|---|
| Could | Could | Could | Could |
Test applications
There is one exception to this rule. To facilitate testing, it's essential to establish a test product that possesses access to either all APIs or a designated group of APIs. To this end, we implement the following naming convention:
Convention: Test party + TEST (in all uppercase)
Example: AT-TEST (representing WPP test)
For the production environment, we will also establish an "AT-PRTG" application. This application will be exclusively dedicated to monitoring with PRTG.
| Internal | Private | Partner | Public | Alternative |
|---|---|---|---|---|
| Must | Must | Must | Must |
Target servers
We've tried to maintain a straightforward naming convention. Ideally, each backend corresponds to a single target server, and the name remains consistent across different environments. When necessary, backend certificates need to be imported for each environment. In some cases, you might expose only a specific part or endpoint of a backend. In such instances, you can use the extension to provide additional, more precise information.
Convention: System + (extension)
Example: ERP, CRM_addresses
| Internal | Private | Partner | Public | Alternative |
|---|---|---|---|---|
| Must | Must | Must | Must |
Key-value maps
Key-value maps serve various functions, and their diverse use cases make it challenging to establish a single, generic naming convention. For instance, they can be employed to store a username and password, which can then be utilized in an API to configure an authorization header for the backend. In the context of this specific example, we've devised the following naming convention:
Convention: System + key name
Example: ERP_username, CRM_password
| Internal | Private | Partner | Public | Alternative |
|---|---|---|---|---|
| Must | Must | Must | Must |