I was reading some articles about code maintainability. Balci wrote 1997 that maintainability is “the ease with which changes can be made to satisfy new requirements or to correct deficiencies”. Well designed software should be flexible enough to accommodate future changes that will be needed as new requirements come to light. Since maintenance accounts for nearly 70% of the cost of the software life cycle (Lindroos), the importance of this quality characteristic cannot be overemphasized. Quite often the programmer responsible for writing a section of code is not the one who must maintain it. For this reason, the quality of the software documentation significantly affects the maintainability of the software product. I can find tons of academic material about software design, but modern API design related is harder to find.
What about design maintainability of modern APIs?
The above was said regarding software as we knew it before the platform and API Economy. I’m not that code oriented person so does not interest me too much. Instead I started to wonder how that relates to APIs and API design. What about modern APIs? Those are designed upfront more often and the design decisions most likely affect the maintainability. API Designers lay the foundation for APIs we use in daily operations and those designs need to be maintained as well. They design the APIs before single line of code is created.
The maintainability of modern APIS can be addressed at least on two levels:
- Design level (how it should behave and what to contain with restrictions) - creation and update + versioning
- Implementation level (the code version)
Design level maintainability
Now I’m more interested about the design level maintainability. Perhaps we should take a look at the design practices from UI field. They’ve been managing “user interface” designs for longer than API designers. UI designers have plenty of tools to select from. Adobe has done some marvelous job in that field as an example. API design tools are a different beast. Those are taking the first baby steps at the moment. The tools I know have little to do with design. Those are specs editors. And I’m not the only one saying this. We need better API design tools. Enough with the rant for now.
Interface design aims
An API is a developer’s UI-just like any UI. It not that different when compared as a concept with GUIs. Yet, it’s completely different in details. It is important to ensure the user’s experience is thought out carefully. So an API should:
- use web standards where they make sense.
- be friendly to the developer and be explorable.
- be simple, intuitive and consistent to make adoption not only easy but pleasant.
- provide enough flexibility to power the majority of the enchant UI.
- be efficient, scalable, while maintaining balance with the other requirements.
Maintainability of the API design or a family of APIs is a huge tasks and responsibility. One of the elements I see as a tool here is the more popular API Design Guides. Guides often provide boundaries and best practices to follow in API design. I would say that the API Design guides are the most significant tool to create easy to maintain API designs. Maintainability is created during the design process. It cannot be added later.
UI design patterns and practices probably give some insights here. Design Guides are really good practice and should be discussed more profoundly here, but I’m kind of familiar with those already so I will not use my time in those here. Read more about API Design Guides from for example from http://apistylebook.com/design/guidelines/
One significant fact should always be kept in mind. You will not likely be the one to maintain the design forever. Someone else has to take over at some point. Design must be easy to understand, follow and adopt. Follow the “Cradle to grave” principle. Company behind the API is responsible for it from creation to retirement. Sometimes the timespan can be really long and design has to be maintained all the time.
Design for Maintainability (DfM)
Another approach would be system design practices. Systemic thinking and related practices. I bumped into Design for Maintainability (DfM). Design for Maintainability emphasizes the importance of timely integration of design and construction knowledge with operations and maintenance (O&M) experiences into project designs at an early stage. Implementing DfM decreases the risk of equipment reliability and uptime being impacted and total life-cycle costs increasing significantly.
The following specifics are included in DfM:
- Standard Design Practice — Maintainability is accomplished through designed–in features such as equipment accessibility, standardization, modularization, ease of maintenance, etc.
- Contract Specifications — Effective specifications include maintainability objectives, thorough operation and maintenance documentation and training needs, and maintenance management system requirements.
- Cross–Functional Involvement — Input from maintenance personnel is incorporated into the maintainability planning and design of the project.
- Pilot Maintainability Program — Small–scale program identifies benefits and costs of maintainability that can be tested with minimal risk.
- Integration into Existing Programs — This approach identifies maintainability best practices that can be integrated into existing programs such as reliability analysis, process hazard analysis, and front–end planning with minimal cost and effort.
- Formal Maintainability Program — Developed, supported, and resources committed from the corporate level of the organization. Maintainability roles and responsibilities are clearly identified. A structured work process is provided to facilitate implementation of maintainability.
- Comprehensive Tracking — Methods exist to capture, document, archive, and share project maintainability lessons learned.
To be continued…
I would assume that both (DfM and UI design profession) of the approaches could provide insights in developing API Design profession. I need to use another night on this topic and write part 2 about this tomorrow. This is intriguing since API design as a profession is relatively new and the role of it will become even more significant in the future.
Some more to read from 100 Days DX
- #100 - The biggest open resource on Developer eXperience so far
- #99 - Hackers - the top 1% of engineers
- #98 - Invalid Open API spec files ruins the developer experience
- #97 - Lightweight API evaluation framework
- #96 - Embracing open source community driven tools development
- #95 - Exploring the multilevel nature of API Design Guides
While you are here...
Check out Platform of Trust in which I've worked to enable best possible developer experience!