Showing posts with label standards. Show all posts
Showing posts with label standards. Show all posts

Tuesday, 19 May 2020

Untangling Governance Definitions - Patterns, Blueprints, Templates, Standards and Reference Architecture

By Aiden Gallagher & Peter Reeves

*Disclaimer: These are our own definitions and might not map to your specific organisation. And, of course, these are our own opinions, and not necessarily those of our employer

Introduction

For the last few weeks, Peter and I have been talking about Integration Patterns, blueprints and architectures to try and boil down a common definition which we can use when talking about these concepts.
We found that halfway through a conversation we would start merging elements and classifying the same integration item as different things.

To remedy this, we decided to write down the definitions as a reference point that we could refer back to. In this blog post you will be able to see these definitions, and when we talk about Patterns, Blueprints, Templates, Standards and Reference Architectures you will know what we mean too.

Why do we care?

Before we share the definitions, it’s important to know why we care about the words themselves. We want to be sure that when we are discussing concepts that we are all referring to the same things and in the same way, related to how artefacts fit into the wider organizational picture and the correct governance procedures when designing systems.

Definitions

Below you will find our definitions and with them an example of how these are applied outside of the computing world. In this example, we will apply them to a housing project and “dwellings”.

Pattern

Definition – A pattern is a refined repeatable concept which is a solution to a common problem.

Example – Given the common problem of a human needing a place to live; have a roof over our heads, running water, sanitation, heat and the ability to cook, a pattern standardises the way we build a ‘dwelling’ that acts as a solution to these problems.

Blueprint

Definition – A blueprint is a detailed design for how to implement a pattern using a certain technology.

Example - A blueprint of the dwelling pattern could be a terraced house which provides dwellings against a limited land space. It could also be a bungalow which provides accessible dwellings for those who cannot use an upstairs.

Templates

Definition – A template is an implementation of a blueprint with further details on the specifications for items of that type. It might be followed exactly, or it might be altered to fit the need of the circumstance.
Example – A terraced house in Darlington was previously built with certain specification. The designer wants to provide more garden space as such they can tweak the template of a terraced house during design. But the template largely remains the same.

Standards

Definition – Standards are an approach, design or method that is applied across all interconnected systems and applications to ensure consistency of approach, and this benefits support, testing, and development.

Example – The plug sockets in all houses are the same size, as that meets the requirements for the majority of household appliances. This means all devices are interchangeable, which in turn means less customisation during build and hence is cheaper to build and more convenient for the end users.

Reference Architectures

Definition – A reference Architecture is a set of documents or information that describe a topology or system that can be used for common and related patterns. The information, if followed, will provide commonality across deployed templates and blueprints.

Example - A large plot of land is bought for building development requiring sewage, electricity, water, gas, and road network. A reference architecture describes how this infrastructure can be setup to accommodate different home styles (patterns) the instructions for building each home (blueprint), and potentially any customisations to the blueprint to fit other requirements (templates, and templated usage). Throughout the whole build process the same style of roofs, doors and windows are purchased (standards).

Integration Example

In the integration world we might apply the above definitions to the following use case.

A hybrid-cloud deployment strategy has been documented which shows how availability, disaster recovery, networking, and deployments of servers, and various business functions might be achieved in a reference architecture for that system.

The cloud deployment has a number of topologies (or building blocks for topologies). These are used as necessary to build integration patterns (e.g. request-reply which needs to solve some high-level problems like: access to a database, transactionality, reliability etc.)

Having selected the reference architecture which will support specific patterns, a blueprints to implement desired patterns using those cloud offerings can be written by the organisation – this could form a high-level design of how the new system will look like, this is further refined and customised in the low-level design. 

Looking at a Hybrid Cloud implementation, there are some orchestrated deployments packaged as part of a cloud offerings to solve specific business needs, which is in itself like an off-the-shelf blueprint combined.

To build the system, a series of templates are used for each cloud product with necessary minor tweaks that meet small nuances of the pattern and blueprint requirements. Throughout all these processes the organization’s standards are used to ensure naming conventions are the same, disaster recovery can be performed by any of the support teams, that port mappings follow the same style for easier communication with the network teams, and any other core business procedures are followed.

The end result is a system that was built quickly, in a reusable, extensible, and familiar way and that is now supportable by the wider organization.

Benefits
By using Patterns, Blueprints, Templates, Standards and Reference Architectures there are obvious tangible benefits:

Standardisation

·      Less complexity when implementing solutions as everything is known.
·      Cost reduction of multiple teams solving the same problems repeatedly (why reinvent the wheel?)

Reusability

·      Once the patterns, blueprints etc. have been shaped and refined, it becomes easier to reuse them than to start the building process from scratch- saving time and energy exponentially.
·      They are easy to use.
·      They are easy to deploy.
·      They are easy to support.

Familiarity

·      There is less project-specific knowledge required when people switch roles as the core patterns (and blueprints) are the same.
·      Individuals are able to get the 'gist' of what is happening in a new project- even for customised docs, build etc- because everything looks and feels the same and was built with the same principles, even if the low-level implementation is slightly different.
·      This familiarity makes it easier and quicker to fix, debug and test new projects.
·      This leads to a reduction in dependencies on individual resources.

Future Proofing for the whole Organisation

·      Improving the pattern by one team improves for all.
·      The whole organisation is carried into modern practices together because of the usage of patterns, blueprints etc.

Limitations

There are some limitations to the usage of Patterns, Blueprints, Templates, Standards and Reference Architectures which tie closely together:

Complexity

·      Sometimes complexity is required, maybe because something has never been done before, or there are new nuances such as security regulations that make a solution difficult to implement using existing patterns.
·      Trying to fit the patterns into these use cases might cause more harm than good e.g. over-engineering, barrier to release time, tendency towards “You aren’t going to need it” (YAGNI) behaviours and a bloated system.

Blocker to change

·      It can be hard to change a pattern because it’s a known entity which people are familiar with. The pattern then becomes a tool to block improvements.
·      It can be hard to get change because the benefits of a new system might not be understood by the wider organisation who must accept these changes.
·      Patterns become tied to governance process. This can undermine the governance process which can be deemed as ‘red tape’.

Stifling Innovation

·      Working only to the pattern can stifle the creativity which comes naturally to a lot of people in an organisation. This means that the pattern and its prescriptive, restrictive methods can lead to a lack of innovation and improvements.
·      It can be hard to get investment for new ideas because there are no any proven benefits, which is perpetuated by a lack of ability to improve existing patterns.

For all these limitations, it is possible with good organisation practices to be able to work around these requirements. This might be by encouraging minimum viable products (MVPs), allowing colleagues to use new tools in their day to day life, and having governance process that look to solve organisational problems and ongoing reviews of current business processes.

Conclusion

In this blog post, we have given our definition of Patterns, Blueprints, Templates, Standards and Reference Architectures, along with a real-world example and a computing example alongside an exploration of the benefits and limitations of using them.


Have any thoughts? Do you vehemently disagree with our definitions? Have a better computing example?  Get in touch to tell us what you think

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