Wednesday, 9 May 2018

Integration Innovators - Part 1

**Note: Any images, text or quotes have been used to provide an overview of the people themselves. I have linked to the relevant sources in the read more, but will gladly remove any part should the subjects or original authors so wish.**

In the last 18 months I have been constantly seeking to get a better understanding of the technologies I work with every day from databases, to Ethernet, to the first compilers, message queues and the underlying network they run on. The list is never ending and what started as a few pages of notes has turned into maybe 30.

What has begun to interest me more and more are the people who brought about these changes, the work they have completed across their lives and the impact it has had on the way we live and the way we do business.

In this post I intend to describe some of the people who I have ‘discovered’ in my research in a hope that my own generation do not forget those who progressed the computing technology that can often be taken for granted. 

Here are a handful of them, in no particular order;

Abhay Bhushan

1.    Abhay Bhushan was born in Allahabad, India in November 1944 and was in the first group of students to attend the Indian Institute of Technology Kapur (IIT Kapur) which was at the time being funded by a consortium of universities including; Berkeley, Princeton and MIT. 

It was at the university that Abhay met mentors like William Schreiber and Harold Huskey who had worked on some of the first ever TVs and computers inspiring him to take up a role at MIT after his graduation to complete his master’s degree.

It was over the next 5 years 1965 - 1970 that Abhay became involved with APRA and APRANET, even attending a meeting at the pentagon for the Defence Advanced Research Project Agency (DARPA) to discuss communication security before getting involved in the Network Working Group whilst working on his MBA at MIT.

It was in one of these meetings where Abhay took the ownership of “a file transfer protocol” having been working with Steve Crocker, Jon Postel, Mike Padlipsky, Vincent Cerf and many more. The group would discuss, build, test and write Requests For Comments (RFC’s) working on a whole host of networking solutions such as TCP/IP, FTP and the email address with different members being tasked with the write up.

FTP - for which Abhay was the author - went on to be the foundation for pushing files from one system to another whether that’s sharing information across branches, uploading to your blog, or to share files securely. It has been expanded, updated and built upon but FTP remains a huge part of the computing world and Abhay is recognised here for his part in it.

Read more: https://tools.ietf.org/html/rfc114https://www.mappingthejourney.com/single-post/2017/09/15/episode-9-interview-with-abhay-bhushan-author-of-file-transfer-protocol/https://www.scmagazineuk.com/ftp-comes-of-age-as-considerations-made-on-how-practicality-is-over-riding-security/article/560138/

Grace Murray Hopper
2.    Dr Grace Murray Hopper was born in New York City December 1906, gaining a BA in Mathematics and Physics in 1928 before achieving both her MA and PhD in Mathematics at Yale University.

From a young age it was apparent that the budding mathematician had a drive to discover, taking apart the family alarm clocks at age 7 just to see how they worked. The same drive saw her through university and her PhD, despite being only 1 of 10 students on a doctoral program of which only 4 were women.

It was this drive that also led her to take a leave of absence from teaching to join the US Navy as part of their Women Accepted for Volunteer Emergency Service (WAVES) program where she graduated first in her class and gained the rank of lieutenant, aiding in the war effort by working on the Mark series of computers.

Working on and off for the rest of her life in the navy, research positions and as a consultant she filled her days with innovating, teaching and thinking outside of the box. One such innovation was her belief that computing could be further used and more widely adopted if it could be written in a human readable way.

She went on to create an operational compiler at a time when many believed that computers couldn’t - or indeed shouldn’t - communicate in English. Instead, she pushed for its use in business tasks like billing and payroll calculation. Later the FLOW-MATIC compiler she had worked on became the basis of COBOL, a language used by up to 80% of all code in existence including in the Navy whom Grace persuaded to adopt the new language.

Whilst this extremely brief summary does not skim the surface of this inspirational woman, her contribution to the world of computing has been phenomenal.

An interesting fact is that Grace Hopper was the finder of a moth in one of the early computers which was causing chaos on the system itself. This later led to the widespread use of the word ‘bug’ to mean a fault in a computer.

Read More: Grace Hopper and the invention of the Information Age (Book) http://www.amazingwomeninhistory.com/amazing-grace-hopper-computer-programmer/http://www.cs.yale.edu/homes/tap/Files/hopper-wit.html

Roy Fielding
3.    Roy Fielding was born in 1965 (same year as my mum and dad) in Laguna Beach, California and describes himself as “part Maori, Kiwi, Yank, Irish, Scottish, British, and California beach bum".

Whilst the youngest member of the five being discussed, he was accredited as one of the top 100 innovators around the world by an MIT Technical Review in 1999 for his work on Open Source projects like Apache Group - of which he is a co-founder - and his work in 1994 when he innovated the web by creating procedures to update web page storage by transmitting information only when a change had been created.

He later began work with Tim Berners-Lee as part of the WWW Consortium (W3C) helping with standardisation of WWW protocols being an active member of several working groups such as HTTP, HTML and URI.
Most notably would be his contribution to the world of web services in 2000 with his dissertation thesis for his degree as a Doctor of Philosophy in Information and Computer Science at University of California, Irvine. 

In the dissertation, Roy discussed the idea of Representative State Transfer (REST) architectural styles and how they can be used in web services specifically by using interoperable, stateless operations such as GET, PUT and POST. 

The RESTful architecture came to be used massively in SOA implementations across the computer industry, especially in integration and this Roy finds himself on my list. At still a young age and continuing his work at Adobe there is yet much more to come.


Frances Allen
4.    Frances Allen was born in Plattsburg, New York in 1932 becoming first a B.S. in 1954 and then an M.S. in mathematics from the University of Michigan in 1957. Whilst initially a teacher of mathematics she later joined IBM - our first IBMer on the list - in order to pay off her education debts but fell in love with the people in the company, so much so, that she remained there for the next 45 years.

It was Frances work in compiler optimisation that gained her the plaudits, after she read the FORTRAN programming manual and became interested in the field. She continued in this vane for the rest of her IBM career, working on some of the earlier supercomputers within the organisation such as Stretch.

Part of this optimisation was the use of her mathematics knowledge to gain computational advantages when analysing data sets. She gained many awards for the work including IBM, ACM and IEEE fellowship for her work in making the programs people loved to use, better.

In 2006, Frances was awarded the ACM Turing Award, a prize given for those who have contributed lasting and major technically important work in the computing field for her years of dedication. Additionally, she is one of the Women In Technology Internationally (WITI) hall of famers.

Read More: https://amturing.acm.org/award_winners/allen_1012327.cfmhttp://www.computerhistory.org/fellowawards/hall/frances-allen/https://www-03.ibm.com/ibm/history/witexhibit/wit_hall_allen.html

Douglas Crockford
5.    Douglas Crockford was born (according to Wikipedia, but I can’t verify) in 1955. Having graduated from San Francisco State University with a Radio and Television degree, Douglas has worked across the board as a technology guru at Atari, yahoo, lucasfilms, paramount pictures and paypal.

What Crockford is well known for his work with JavaScript and specifically the object notation called JSON which he discovered and has popularised ever since by documenting formally the notation for the JSON media type in  RFC 4627 and through a dedicated website. Additionally, he has published a book called “JavaScript: The Good Parts” which was released by O’Reilley in 2006.

What makes JSON so key is that it is a self-describing, hierarchical structured simple text which is both easy to use and more compact than its XML counterpart by around two thirds and although its name contains “JavaScript” it is actually language independent.

It is now widely used, and in some cases like Twitter, it is the only data expression exposed in APIs due to the simplicity and ease with which it is consumed. Whilst JSON will be Douglas’ lasting legacy his other work also provides much to be admired including his creation of the JSLint and JSMin software which analyses and minifies JavaScript code respectively.

Read More: https://tools.ietf.org/html/rfc4627https://www.crockford.comhttp://www.json.org/fatfree.html


I hope you enjoyed this little read and will go out and learn more about the people mentioned.

Who would go on your list of Integration Innovators? Feel free to comment and I can add them to Part ‘N’ of what I hope to be a little series over the next year. 

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