Tuesday, August 24, 2021

2021-08-24 Tuesday - Book Review - Designing API-First Enterprise Architectures on Azure


image source: Amazon.com

 Designing API-First Enterprise Architectures on Azure: A guide for architects and developers to expedite digital transformation with API-led architectures, by  Subhajit Chatterjee.

Packt Publishing; 1st edition (August 24, 2021)
290 pages

My review on Amazon:



Full Disclosure: I was provided a preview PDF copy of the book, by Deepak Kumar (Marketing Coordinator, Packt Publishing)

My Summary

A decent high-level/broad survey/roadmap - but lacking sufficient "meat"

This book provides a broad, high-level, enterprise architecture overview of API design – with some context based on the Microsoft Azure cloud platform – but many of the topics/concepts can easily be translated/applied to any commercial cloud vendor’s platform.

The primary value of this book is as more of a summary/roadmap - than a detailed technical or architecture guide for implementing an API strategy for the enterprise . The topics in the well-organized chapters – and the many links to the additionally suggested references/ reading – is worth the price of the book for the busy architect, developer, or IT manager.

What I Particularly Liked:

- The framing and weaving of business drivers, requirements, forces, constraints, concepts, and examples through the lens (and continuity) of the simulated case study ("Packt Insurance, Inc.") discussion that is threaded throughout the book.

- The “further reading” citations at the end of each chapter – and in particular – that it is not simply citations of additional Packt books.

- Chapter-1’s definition of service scales (re: page-7, microservice, mini-service, macroservice) – as well as the key benefits of an API-led architecture (re; page-11,  four points enumerated).

- Chapter-2's framing of APIs as digital services - and the use of service and personas maps.

- Chapter-2’s illustration of the concept of API layers (re: page-23) – an important concept in the design of enterprise API architecture strategies.

- Chapter-3's level-setting of Architecture Principles - and the discussion on API architecture styles - as well as the discussion on Serverless APIs.

- Chapter-3’s Figure and Table 3.1 – Agile architecture evolution process (re: page-41)

- Chapter-4's coverage of the Security Development Lifecycle (SDL) - as well as the elaboration on defining SLOs and SLIs for APIs. 

- Chapter-5's coverage of contract-first API design - and in particular, promoting the use of the Open API Specification (OAS). 

- Chapter-6's discussion on secure by design, as well as design patterns.

- Chapter-7's focus on DevOps - and the enumeration of DevOps Capabilities that are important to APIs design, development, operation - as well as the four supporting "pillars".

- Chapter-8's coverage of Enterprise Application Integration (EAI)  patterns. 

- Chapter-9's discussion on monetization - and APIs as potential revenue generating mechanisms.


Suggestions for Improving the Next Edition:

Overall, I am a bit disappointed in this book – as it far too often only provides a very brief paragraph to describe an Azure capability – without providing any discussions in the book of concrete examples in code – and then suggesting the reader follow a link to “Find out more…”. See pages 55-56 for examples (re: App Service, Function App, Logic App) – when the value of the book could be greatly increased by providing examples – and counter-examples (how to properly use these services, and how you might inadvertently abuse them).

What is keenly missing – is the author’s practical, first-hand,  insights on how/when to use which of these services – to solve particular kinds of solution design problems.

Consider increasing the length of the book (by 150-200 pages) to provide details on the following topics (that are only lightly referenced in the book):

  • Domain-Driven Design (DDD)
  • Event Storming
  • Behavior-Driven Design (BDD)
  • API anti-patterns
  • API Authentication/Authorization (beyond the brief mention on pages 80-81).
  • High Availability Patterns (re: page-98) – would greatly benefit from having some architecture diagrams to illustrate these patterns.

Given that the book’s case study is based on a simulated insurance company – readers of Chapter-5 would greatly benefit by the author exploring how query parameters for an HTTPS GET – that might potentially expose Personally Identifiable Information (PII), Personally Protected Information (PPI), or Personal Health Information (PHI) – should NOT be passed via a GET query – but should be sent as content in an HTTPS POST.

Additional chapters to explore the capabilities of such 3rd party tooling as Swagger Hub, or Postman (beyond their brief mention on page-158)  – as part of a complete view of their potential use in a multi-team enterprise API design/build/test pipeline – would be a goodness.

Chapter-8’s discussion of Azure API Management (APIM) – could be greatly/beneficially expanded to discuss how common/reusable/shared Open API Specification (OAS) fragments should/could be managed – in the absence of such capability within Azure (e.g., leveraging SwaggerHub, or Postman Enterprise, or ?). This is a fundamental/common enterprise-class problem. Additionally, guidance on when/whether an enterprise should consider having only one APIM instance vs. multiple APIM instances. 

Chapter-8’s discussion of the API Developer Portal – could be greatly/beneficially expanded to discuss what are the APIM options/capabilities to restrict access to API definition content – for different internal teams, as well as external partners, or 3rd party API developers.

Chapter-8 should also include a discussion of Azure’ssupport for CMS-mandated FHIR APIs (re: Healthcare).


Missing/Broken Links

(I grew weary of finding so many of these - that I gave-up testing links in the book)
  • The github link on page-108 is broken.
  • The link is missing on page-160 for “Microservices Architecture”) under Further Reading.
  • The link is missing on page-165 to the DevOps Dojo white belt foundation.
  • The URL for the link is broken/invalid on page-175 to the git-handbook.
  • The URL for the link is broken/invalid on page-185 to the Azure Monitor info.
  • The URL for the link is broken/invalid on page-189 to the devsecops.
  • The URL for the link on page-191, mastering markdown, returns a 404 error code (“File Not Found”) – because the URL for the link is incorrect.
  • The URL for the link on page-192, Wikipedia, value stream mapping – is not correct. Also see the  invalid URL link for the “3-explore-first-foundation”
  • The URL for the link on page-193, “4-explore-secondfoundation” is not correct. Also see the invalid URL link “2-explore-thirdfundation-pillar” on the same page. Also note the URL link is missing for the “pillars/3-explore-last-foundation”
  • The URL for the link on page-215, see “/product-categories/integration” - is missing.

 I have reported these to Packt.

Table of Contents:

Section 1: API-Led Architecture in the Digital Economy
1 - Evolution of Enterprise Solution Architectures
2 - APIs as Digital Connectors

Section 2: Build Reliable API-Centric Solutions
3 - Architecture Principles and API Styles
4 - Assuring the Quality of the API Service (or Product)
5 - RESTful APIs –􀁢the New Web
6 - API Design Practices
7 - Accelerating through DevOps Essentials

Section 3: Deliver Business Value for a Modern Enterprise
8 - API-Centric Enterprise Integrations
9 - APIs as a Monetized Product


© 2001-2021 International Technology Ventures, Inc., All Rights Reserved.