**NOTE: Though I am an IBMer, these are naming conventions I personally endorse but are not necessarily endorsed by IBM as an organisation as per all posts on my blog**
Introduction
IBM API Connect has a host of free text variable, parameter, profile and component names. Whilst these are and can be named whatever you like, it is good to follow some uniform naming standards.
Often each new business, value stream, brand, department and individual people will have specific ways in which they like to name. This leads to every object being named different for each new department and team. To alleviate this, I have created the following naming conventions which can be used.
Table of Contents
Case Study
All examples described in this document will reference an imaginary Commercial Bank called UKBank that specialises in Mortgages, Loans and Current Accounts, they also provide open APIs for bank locators etc.
The Bank is using Organisations as their environments i.e. SIT01, OAT01, NFT01, LUAT01, PROD01. Their catalogs relate directly to their specialisations with spaces in Current Accounts to isolate traffic for their payments from balance enquiries.
Naming Objects as ‘Default’
Where possible, no object in the API Connect Cloud should be left with a default name of ‘Default’. This causes confusion, makes email notifications difficult to follow and can lengthen routine maintenance and management processes as an understanding of what each element does is made apparent.
Display Names and Object Names
In API Connect, most objects have both a display name - sometimes referred to as a Title - and a ‘name’ which refers to the object name. Where appropriate, both display and functional names have been given.
1 API Development
1.1 APIs
There are many well documented conventions for naming APIs and will often follow company preference.
IBM have released a guide for APIs in past redbooks: Getting Started with IBM API Connect Concepts and Architecture Guide (http://www.redbooks.ibm.com/redpapers/pdfs/redp5349.pdf)
Additionally, there are articles that describe API needs around versioning and standard formatting of naming, versioning and url etc. (https://www.ibm.com/developerworks/library/mw-1710-phillips/index.html)
https://api.ukbank.co.uk/mortgages/v1.0/rates
https://api.sandbox.ukbank.co.uk/loan/v1.1/quote
https://developer.ukbank.co.uk/v1.0/balance
1.2 Product
Products contain a logical grouping of APIs which will be callable once a Developer Organisation has subscribed to its plan. The Product should accurately describe the purpose of the collection of APIs.
Product names should include dashes and not underscores and should not contain numbers. Version numbers should not be defined in the Product name, this causes confusion as it is static against the dynamic version number that displays next to the Product.
If there is a need to differentiate between brands these are appended in brackets at the end of the product.
Title
|
Name
|
Current Account Information (England)
|
current-account-information-england
|
Current Account Information (Scotland)
|
current-account-information-scotland
|
Mortgage Offers (England)
|
mortgage-offers-england
|
Mortgage APR (England)
|
mortgage-apr-england
|
Mortgage Payments (UKBank)
|
mortgage-payments-ukbank
|
1.3 Plans
Plans are used for rate limiting of API Calls and monetization of APIs. Developer Organisation subscribe an Application to a Plan, not a Product. Each product can have multiple plans which will have different costs and potentially rate limits. Additionally, different plans may conform to predefined contract agreements between third parties, public and internal users.
When an Organisation has a predefined, well documented and well understood convention for logical grouping of APIs and their limits, these should be continued in plan names. This would typically map to a standard selection of upgrades.
Plan 1 - Title
|
Plan 1 - Name
|
Plan 2 - Title
|
Plan 2 - Name
|
Plan 3 - Title
|
Plan 3 - Name
|
Basic
|
basic
|
Standard
|
standard
|
Advanced
|
advanced
|
Bronze
|
bronze
|
Silver
|
silver
|
Gold
|
gold
|
Small
|
small
|
Medium
|
medium
|
Large
|
large
|
2 Topology
2.1 Provider Organisations
Provider Organisations might be named after an environment i.e. SIT01 or by an Organisations business unit i.e. UK Sales, UK HR.
An Organisations display name may be several words, each beginning with a capital letter. Its logical name must represent the display name, it must not contain spaces but instead should use a dash rather than an underscore. For best display and reference, it is recommended that the Organisation not be any more than 2 words and 15 characters (Maximum length: 81 characters).
Where multiple environments may exist of the same type i.e. System Integration Test, the environments unique identifier should be two numbers after the environments abbreviations beginning at ‘01’ through ‘99’.
Display Name
|
Name
|
OAT01
|
oat01
|
SIT01
|
sit01
|
SIT02
|
sit02
|
LUAT01
|
luat01
|
UK Sales
|
uk-sales
|
UK HR
|
uk-hr
|
2.2 Catalog
Catalogs provide a logical separation for Products and their APIs with an Organisation. They also determine the developer portals that will be used for subscription of Plans within APIs as catalogs can have a single Developer Portal Site and therefore each catalog can push only to a single portal site. The actual name given to a catalog depends on the chosen distribution of Products, APIs and intended use of Organisations, though it commonly becomes split by a brand or value stream.
Catalogs names should be a single descriptive word. However, if a double worded Catalog is used it should not use camel-case and should have capitals for the first letter of each word and a space used for the display name.
Display Name
|
Name
|
Mortgages
|
mortgages
|
Open
|
open
|
Loans
|
loans
|
Current Accounts
|
current-accounts
|
2.3 Spaces
Spaces provide a separation of Products and APIs within a single Catalog. Each space should describe the separation it is bringing with its name.
Spaces names should be single word and descriptive. However, if a double worded Space is used it should not use camel-case and should have capitals for the first letter of each word and a space used for the display name.
Display Name
|
Name
|
Balance
|
balance
|
Payments
|
payments
|
England Stores
|
england-stored
|
England Regulations
|
england-regulations
|
2.4 Communities
2.4.1 Developer Organisations
Developer Organisations can be created both on a Portal site and also on the management server. Typically, the Portal Site would be explored by external entities either external to the business itself or external to Provider teams, brands and value streams. Internal Developer Organisation such that have their Developer Organisations created for them will be defined in the API Manager WebUI.
The naming convention to be applied here should follow existing internal naming solutions for applications. Where no existing convention exists, the format should follow the format of Organisation-ValueStream-TeamName.
Developer Organisation
|
UKBank-HR-Compensation
|
UKBank-Mortgages-Test
|
UKBank-Mortgages-Development
|
UKBank-Mortgages-View
|
2.4.2 Applications
Applications should be created with its goal and purpose in mind. The name of these applications should be concise, should all be lower case and obvious what the application does.
Title
|
hr-employee-payment
|
hr-employee-illness
|
mortgage-test-ivt001
|
mortgage-test-ivt002
|
mortgage-test-ivt003
|
mortgage-test-endtoend
|
2.5 Management Services
2.5.1 Service Name
In IBM API Connect v5, there is a single management service called Management. This cannot be changed.
2.5.2 Server Name
Server names should reference the server address/hostname being used. This helps easily identify management servers and issues that may arise i.e. dissociation.
Where server names already exist within the company or organisation, this standard should be used and the name used throughout. This consistency allows interdepartmental teams to quickly understand and identify issues.
Server Name
|
Server Address
|
MGR0012
|
10.132.41.12 mgrsrvr0012.prod.machine
|
2.6 DP Services
2.6.1 Service Name
Services should be named relating to the Organisation they are being used by and should be named in a descriptive form of the domain they are representing. This service will be used by catalogs and spaces to define the gateway services they will use, so a descriptive name is important.
Title
|
SIT01 Mortgages DP Service
|
OAT01 Current Account Payments DP Service
|
PROD01 Open APIs
|
2.6.2 Server Name
Server names should reference the Organisation or Domain they are being used for and should be identifiable to the server they are representing to avoid confusion for debugging. We use gateway identifiers to precede the server identifier.
Server Name
|
Server Address
|
SIT01 GWY0022
|
10.132.41.22 gwysrvr0022.prod.machine
|
2.6.3 Extensions
Extensions are deployed to a single domain. They should include a version number which can be incremented as and when changes are made. Alternatively, or in conjunction with the version number, a date stamp may be appended to the end of the string to further describe when the extension was compiled. Names should be descriptive of the function being performed, should not contain spaces but instead dashes. The file should use full words and not abbreviations.
Filename
|
api-certificate-updates-v1.0.zip
|
api-certificate-updates-20180101-0323.zip
|
api-certificate-updates-v1.0-20180101-0323.zip
|
2.7 User Registries
A User Registry should be easily identifiable to anyone looking at the system. Typically, it would describe what component it is for, where the registry is based and then the fact it is a user registry.
The name cannot contain spaces, should be entirely in lowercases but should be shorter than the Title/Display Name. The registry location and “user registry” should be condensed to just the first letter of each.
Display Name
|
Name
|
API Manager Local User Registry
|
api-manager-lur
|
Cloud Manager Docker User Registry
|
cloud-manager-dur
|
2.8 Roles
Each role within API Manager can have multiple words for its Title/Display Name to a maximum of 81 characters (to be represented equivalently in the name). These should describe the type of permission being given.
The name must be lowercase and use dashes instead of spaces.
Display Name
|
Name
|
Community Viewer
|
community-viewer
|
Role Assigner
|
role-assigner
|
2.9 TLS Profile
TLS profiles can be used for communication with the API Connect Cloud Manager and the Gateway or for a TLS handshake with a load balancer. These cloud-based TLS Profiles are defined in the Cloud Manager.
Additionally, TLS profiles can be defined in the API Manager to be used by APIs to call either other APIs on the same gateway or some form of implementation layer downstream such as an internal load balancer or microservice.
2.9.1 Cloud Console
The name given for Cloud based TLS Profiles should have the following format; component-tls-side-profile, component relates to where the profile is used, and side is whether it is a server or client profile. The Display Name/Title is the same but with spaces instead of dashes.
Display Name
|
Name
|
Default TLS Server Profile
|
default-tls-server-profile
|
SNI TLS Client Profile
|
sni-tls-client-profile
|
2.9.2 APIs
TLS Profiles to be used by APIs for handshakes to endpoints should have the following format; purpose-tls-location. Where purpose should show the intended use of the profile and location should describe the endpoint where the handshake will occur. The Display Name/Title is the same but with spaces instead of dashes.
Display Name
|
Name
|
Authorise API TLS IHS
|
authorise-api-tls-ihs
|
3 Developer Portal
The developer portal is a server which stored all the information about each of the Clouds portal sites. There are limited objects that require naming conventions within the Portal such as Roles, Page Names and Drupal Modules.
3.1 Roles
Roles should follow the rules already defined earlier in the document: Roles.
3.2 Developer Portal Modules
Modules within the Developer Portal allow additional functionality with the Portal Site such as configuration of LDAP for portal delegated user registry, live chat functions, OpenID Connect and many more.
Module names within the Developer Portal should follow Drupal Standards.
4 v2018.x
4.1 Availability Zone
Availability Zones should be descriptive and are organised by regions, global separation, or for physical/logical separation of datacentres. The Title can use spaces, capitals, lowercase etc. but a short one or two-word title is preferred. Abbreviation may be used
Title
|
Name
|
US Availability Zone
|
us-availability-zone
|
Hampshire Availability Zone
|
hants-availability-zone
|
Newport Availability Zone
|
newport-availability-zone
|
LDN South Availability Zone
|
london-south-availability-zone
|
4.2 Portal, Analytics and Gateway Service(s)
Services should describe the type of service and match the location for the availability zone. There should be no spaces and each new word should start with a capital letter. Abbreviations should match those in the Availability Zone.
Title
|
Name
|
USPortal
|
us-portal
|
USGateway
|
us-gateway
|
HampshireAnalytics
|
hants-analytics
|
LDNSouthPortal
|
ldn-south-portal
|
4.3 OAuth Provider
OAuth Title should match the OAuth Provider being used exactly.
Title
|
Name
|
Zendesk
|
zendesk
|
Ubuntu One
|
ubuntu-one
|
No comments:
Post a Comment