Welcome to Software/Service/API Design Practice Repository (DPR) (pronounced "deeper")!
This public repository collects method elements and practices from various methods (old and new) that are applicable to service-oriented analysis and design (and beyond).
News (Feb 7, 2023): See Medium story "Design Practice Repository and Reference: GitPages and eBook Enhanced".
This repository targets the following software engineering roles, ordered from specific to generic:
- (Micro-)Service designers
- API product managers/owners, developers, testers, maintainers
- Software architects specializing on application integration and APIs
- Any software architect
- Any software engineer
DPR is organized around artifacts, templates, activities, and techniques which are applied/performed/used by team members taking one or more software engineering roles:
DPR contains three types of method/practice elements:
- The artifact and template descriptions might be a good first stop. Try Y-shaped Architecture Decision Records (ADRs).
- Next up would be activities and techniques. You may want to start with our Stepwise Service Design practice.
- Also there, but not very deeply populated are the roles and personas: Application Architect, API Product Owner.
The activities and artifacts that we have collected so far are:
There is an introductory blog post. And the quick start tutorial takes you through the repository structure in a small sample scenario. The deeper API design tutorial (in draft state) is a good starting point if you like to learn by example (and are willing to invest a little more time).
We also provide some background information on methods and practices, including a bibliography.
Version 1.4 adds five artifact templates as output of Architecture Modeling:
- Quality Attribute Scenarios (QAS)
- Context Diagram
- Overview Diagram
- Component Diagram
- Deployment Diagram
Version 1.3 was a content hardening and maintenance release.
Version 1.2, released on December 7, 2020, added one activity and one artifact:
- Story splitting for planning and design purposes
- Component, Responsibility, Collaboration (CRC) cards, an OOAD veteran repurposed for architecture design
Tutorial 1 also was enhanced, as well as several other activity and artifact descriptions. We also added (even) more pointers to background information.
We have copy edited all content, provided additional references, and updated various external links.
November 8, 2022: "Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges", published in the Addison Wesley Signature Series curated by Vaughn Vernon, references DPR and features sample artifacts such as domain models, Y-statements, and API descriptions. Learn more.
April 8, 2021: The DPR content also comes as an ebook now. The latest version is available on Leanpub.
According to Martin Fowler, a service is a component with a remote Application Programming Interface (API). And services and their APIs come in different sizes, hence an engineering approach to designing them is required. That's all there is to say!
If you want more conceptual clarifications, see this blog post, this presentation, or this article for a definition of microservices and positioning as an implementation approach to SOA.
The Microservice API Patterns (MAP) website, introduction, and pattern papers go even deeper and introduce terms such as endpoint, operation, and message representations.
DPR applies a best-of-breed approach. Our metamodel adopts parts of Chapter 2 from "An Architectural Decision Modeling Framework for Service-Oriented Architecture Design"(SOAD):
This terminology maps to that of other method engineers like this:
| This repository | Agile community (glossary) | OMG SPEM 2.0 (PDF) | Open Unified Process (UP) and other UP variants |
|---|---|---|---|
| Role | Persona, team member | Role | Worker, stakeholder |
| Activity (with steps) | n/a (not plan-driven, backlog item types come close) | Task (with steps) | RUP: activity, OpenUP: task |
| Artifact | No direct pendant (template? documentation?) | Work product | UP: artifact |
| Technique (part of activity description) | Practice | No direct pendant (tool comes close) | UP: guidance, guideline |
In short, activities describe work to be done, techniques (or practices) help doing so; more than one technique might support an activity. For instance, use case modeling and user story telling are two techniques to elicit functional requirements. Artifacts are deliverables of activities, templates suggest content and structure for them. For example, an architectural decision log (an artifact) may come as a Nygard Architecture Decision Record (ADR), as a Y-Statement, as a Tyree/Akerman table, etc. Techniques and tools support and/or partially automate the activities.
The above terms establish an ubiquitous language (or domain model) of service design and agile architecting — in the (bounded) context of this repository. 😉
Note: Method adoption is eased if you make your methods mighty.
The creation and release of DPR was partially supported by the project "Domain-Driven Digital Service Engineering" funded by the Hasler Foundation.
Contributors (input, technical writing, feedback):
Stefan Kapferer and Oliver Kopp reviewed selected repository content and structure. Many members of our professional networks provided input and/or inspiration through discussions, workshops, joint client projects and many other ways. Thank you!
If you would like to help improve this collection of software/service/API design practices:
- Feel free to create GitHub issues.
- Submit pull requests. If you do so, we assume that you own the IP you submit, agree to open source it under the license of this repository, and therefore comply with this Developer Certificate of Origin.
- The "contributing" folder has templates for artifact, activity, role descriptions.
- Contact us to discuss collaboration and integration opportunities.
More information can be found here.
title: Design Practice Repository (DPR)
owner: Olaf Zimmermann (ZIO)
date: "01, 27, 2023"
copyright: Copyright 2020-2023 Olaf Zimmermann (unless noted otherwise). All rights reserved.
This work is licensed under a Creative Commons Attribution 4.0 International License.
