Thursday 3 May 2018

IBM API Connect Naming Conventions

**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