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 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:

Current practices

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:

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