Business Services and APIs: 101

Business oriented service design and implementation is becoming increasing popular with organisations looking to move beyond traditional systems integration led services. This top-down approach needs to start with business domain owners and their processes, documenting the core and supporting business capabilities they present to their customers so that they can be analysed to produce technology blueprints which projects can implement

These business story led technology blueprints are API specifications and their implementations are Domain services and organisations need to do more of these Business Led Domain Service design to reduce duplication and increase collective resonance

There are still quite a few questions that business stakeholders need answers before buying in to a top-down approach like What are Business Services? How do they differ from APIs? Why do we build these from Business capabilities vs grooming technology integration led services? How does this approach provide value and reduce costs?

Let us go through some of these frequently asked questions in this post

Business Domain Services: Frequently asked questions (FAQ)

What are Services and what is an API ?
- Services are the digital implementation of your Business Capabilities and Features as technology. So Services are an expression of your business functionality via technology endpoints and we often interchangeably use the term APIs to say the same thing
- A service interface is the Blueprint of the this digital implementation of a business function and is sometimes called an API. We tend to conflate the term API with
  - The thing that implements various functions for reading, changing and notifying on change of business data i.e. a collection of technical services in a logical domain – I prefer to call this a Domain Service
  - The thing that implements an endpoint (like Create Customer) – I prefer to call this an API endpoint
  - the thing that contains the blueprint of the service like a contract – I prefer to call this the API contract
- Services can be “system” services (i.e. from Salesforce) or “domain” services ( specific to some business function i.e. Policy, Lending etc or common capability i.e Document Management)
Why do I need services?
- You need services for many reasons including
  - Facilitating information exchange internally between systems to enable business users to operate efficiently via single pane of glass
  - Customers self-service via portal/mobile to reduce running large customer service teams
  - Accelerating Partner integration with electronic services that are self-describing, support security/customer consent models and are easy to integrate and play with by an outsider while not requiring internal support teams or investment
Why do I need to Domain Services?
- Domain services vs System services are a way to do top-down business oriented services
- Building domain services requires understanding boundaries, capabilities, information mastering and collaboration between service providers and consumers. This leads to clear ownership of data and interaction as-a-service between teams operating in contexts leading to autonomy, faster rate of change and ability to scale. Apple and AWS employ these practices to scale
Wait but we have Domain Services, except we built them ground up and in projects
- Bottom up, project led services lack the broader perspective and lead to “separate-ways” type interaction (see Strategic DDD patterns) which leads to duplication of services, increased cost of ownership and more importantly it leads to collective dissonance as an organisation presenting it services to its consumers. This means there is no clear alignment of implemented services to a business capability or traceability of integrations to business contexts leading to increased cost for new internal and external projects
- If we do not orient deliberately then we work our way to a set of services accidentally
- Most organisations that start with technical systems integration tend to see their offering as these services and
What is the difference between Business services and Domain services?
- They mean the same thing – Business domain. They provide services that are aligned to business capabilities and emit events that signal change in some business state
- They sit over one or more system services that implement them
- Some of these services like Customer, Document, Identity etc span lines-of-businesses (LOB) and make for great reusable services
- Others are very specific to the core business functions of a LOB and tied to their internal language and change cadence
- Experience or Consumer adapters invoke business services & listen to their events
How do we make business services more reusable?
- Finding out common capabilities across LOBs to build common functionality is the key
- This needs to happen top-down by cross portfolio teams (business and tech) because delegating to bottom-up processes such as projects will always lead to multiple copies of a capabilities with varying interface and implementation due to the project silos
- Start with obvious services such as document management, identity management etc which are context free (i.e do not require specific business context implementation) and can be reasoned as pure capabilities such as inbound document management, document upload etc
Our LOB is a part of a large set of LOBs / how do we build business services to maximise reusability?
- Start with business SME interviews across the entire portfolio to identify common capabilities
- For a large cohort use techniques such as “Business Context Canvas” which is a short 1-2 hr session to interview SMEs and document context, actors, behaviour
- For detailed sessions and smaller group use Domain Storytelling (1 per process in 1-2 hr workshop)
- For a chaotic but quick large scale view use Event Storming workshops (1 per core process in 2-3 hr workshops)
Wait this sounds like we need to do Business SME interviews and spend a lot of time upfront to capture contexts etc, can we speed it up with process maps or technical experts?
- It is hard to build a business led strategy and business services without upfront planning and this needs listening to your core stakeholders
- It is important to interview and look for common as well as unique capabilities. For example, if cross-LOB needs are “submit a form, the some assessments happen, each assessment is some specific human tasks which needs to show up in a digital workers list of tasks” then there are a lot of common capabilities we can build to serve both businesses while keeping our cost of ownership (number of moving parts) low. Ask then, if one part does look to change its process to differentiate itself in the market or for compliance etc can it do so by itself? Is it autonomous
How do we discover business processes to document domain stories?
- Use Domain Storytelling
- Then do analysis using a business context canvas
- Build context maps
- Build domain models
- Design APIs and host them
Is there a canvas to support the SME interviews or some structure?
- Yes there are a few canvases like this https://github.com/ddd-crew/bounded-context-canvas
- Or you can build your own
  - Core contexts
  - Actors
  - Behaviours & reasons
  - Collaboration across contexts (shared via common artefact or, via services? In partnership or customer-supplier )
  - Value: Key gains
  - Opportunity: Key pains
  - Aspirations: How do they think this could be better, whats in the current roadmap, What should be but missing
  - Competition: What are others doing
What are the steps from design to implementation for this top-down approach?
- Use Domain Storytelling
- Then do analysis using a business context canvas
- Build context maps
- Build domain models
- Design APIs and host them
- Build design mocks using the APIs
- Write tests against the API designs early and cover the journeys
- Learn to measure the APIs for numbers of contexts, personas, volumes and compute overall value and complexity
- Then start with small incremental technical releases from the designs – beta test the APIs with some consumers, publish events and hold state locally before integrating with downstream systems
- Implement features in internal technology systems replacing existing integrations (integration) or leveraging them (via a local datastore)