If API Architects Built Toasters

If I buy a toaster in Australia, I expect an Australian plug.

Not a "company proprietry" plug. Not a “platform-specific connectivity experience.” Yet that is still how too many APIs feel, especially in industries that should do better: banking, payments, healthcare, insurance. Completely different request shapes, response models, auth flows, error semantics, and documentation styles.

That annoys me because other industries solved this decades ago. Electrical appliances conform to sockets. Phones conform to network standards. Browsers eventually converged on common JavaScript and CSS behaviour. But in APIs ignoring interoperability is still ok.

Same task, four banks, four integration models

NAB’s payment capture request:

POST /pts/v2/payments/{id}/captures

{
  "clientReferenceInformation": {
    "code": "ABC123"
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "100.00",
      "currency": "EUR"
    }
  }
}

Now CommBank:

POST /v1/charges/{id}/capture

{
  "amount": "100.00"
}

Westpac:

POST /transactions

{
  "transactionType": "capture",
  "parentTransactionId": 1179985404,
  "principalAmount": 100.00,
  "orderNumber": "ORDER-123"
}

And finally, ANZ (JSON? Nah)

vpc_Command=Capture
vpc_TransactionNo=123
vpc_Amount=4995
vpc_User=amauser
vpc_Password=Password12

Go and write 4 different handlers. Connecting to 50 banks? Write 50 handlers and good luck maintaining them! Or pay to middleware platforms such as Frollo or Basiq.

The browser wars eventually ended because the industry stopped pretending incompatibility was healthy competition. W3C and related standards bodies pushed shared standards for HTML, CSS and the DOM, while JavaScript behaviour converged into the ECMAScript standard. Today browsers still compete, but they compete on performance and features, not on whether web-page works in one but not another.

APIs need the same maturity: less vendor creativity, more interoperability. Follow the industry leader or pioneer. Don't be shy to copy competitor's spec, but make API faster, more secure and reliable.