Merge pull request #136 from kyyberi/feature/day71

Done

_posts/2019-09-24-71.md

@@ -0,0 +1,90 @@
+---
+layout: post
+comments: true
+title: "#71 - API Design guide would be the configuration for the API Design tool"
+date: 2019-09-24 03:32:44
+image: '/assets/img/day71/blog.png'
+description: "What is it and how to foster good maintainability"
+handles: "" 
+tags:
+- DX 
+- 100DaysDX
+- DfM
+- Design
+- Maintainability
+- Design Guide
+
+categories:
+- DX
+- 100DaysDX
+twitter_text: "#71 - API Design guide would be the configuration for the API Design tool"
+---
+
+Yesterday [I touched the API design maintainability a bit](https://100daysdx.com/70). This is something I'm new to. Yesterday I wrote that API design maintainability can be seen from two angles: the design and implementation. The third aspect is the maintainability of the code written against the API. Again add the consumer to the picture. The one we always need to consider. 
+
+Lately I've become more interested about design as we are going heavily on APIs at Platform of Trust. Our API development process is about the turned from code-first to design-first driven process. The code-first worked in the beginning since it enabled somewhat faster start and most of the APIs were internal. Now we need to change modus operandi to more sustainable model. That is design driven development. The amount of APIs is rising and the worry of API design maintainability is becoming more important. In other words I'm solving a rising problem. 
+
+## Design tool matters
+
+Maintainability of the API Designs starts from getting hands on proper designer thinking fitted tools. The early desings for REST APIs were written with text editors. I remember that time. I started to write API designs when the API spec war was still on-going and RAML, Swagger and API Blueprint were battling for the pole position. I sure as hell learned the spec. But that had nothing to do with API design. **I was just learning the formatting. API design was code-first driven.** We are not wittnessing API development to be Design driven, but we still force the designers to do designs code-first. I bet there are already some design tools which are more sophisticated than good old Swagger editor. 
+
+## Modularity 
+
+The API design tool should enable easy modular reuse of components just like in UI design tools. What is reusable component then? In UI design those are pretty small elements like buttons. Pattern libraries, also known as front-end style guides, UI libraries, or component libraries, are quickly becoming a cornerstone of modern interface design. 
+
+But for the designer that OpenAPI spec text should not be shown, but it should be visual element. But from where to get the formatting and boundaries for reusable API components? 
+
+## Convert API Design guide to reusable components
+
+That is what UX designers do nowadays; use existing libraries of components or create own library tailored for bigger platform or alike purpose. What if that is applied to API desing? API is a interface which is designed as well. It's just not so visual as a result. It has patterns well. Even single API has patterns. **A group or family of APIs should definitely have patterns.** 
+
+<blockquote>API Design Guide is now a for humans written pattern library. What if API Design Guide would be converted to ready-made machine-readable components for the APIs? </blockquote>
+
+Then API designer would pick the general elements from the library and reorder them. Perhaps fine-tune parameters. I would actually start the design by defining the needed functionality in the API first. With natural language. Then machine-learning (possibly not even needed) based system would convert that into structure suggestion (by using the component library).
+
+## Let's try it out
+
+Lets elaborate a bit what I mean by the above. This is probably just ridiculous and not even nearly as sophisticated as it should be how cares. With APIs a simple reusable component would be using GET method to list items. That is in almost every API. The endpoint would have standard parameters (defined in API Design Guide):
+- orderBy
+- limit
+- offset
+
+So if for example I would write as requirement: "_API must be able to list all products_" the design tool would use the precomposed component which would be used as follows: 
+
+```
+GET /products/?orderBy&limit=200&offset=
+```
+
+As a OpenAPI spec that would look like
+```
+  /products:
+    get:
+      summary: "List all products"
+      description: "List all the products from catalogue. Sortable by categories. You can limit the return set size and define offset from which product to begin."
+      parameters:
+      - name: "sortBy"
+        in: "path"
+        description: "Sort order, optional parameter"
+        type: "string"
+      - name: "limit"
+        in: "path"
+        description: "The maximum amount of products to return. Default is 50."
+        type: "integer"  
+      - name: "offset"
+        in: "path"
+        description: "The position of product in list from where to start."
+        type: "integer"  
+```
+<blockquote>
+In short, API Design guide would be the configuration for the API Design tool.</blockquote> 
+
+This way it would be used more and API quality would most likely increase. We would need de facto standard to define API Design Guides...or then use machine learning to read settings from current for humans written API Design Guides. 
+
+## Don't force me to fiddle with formatting
+
+Designer should not be dealing with the raw spec file unless absolutely necessary (very rare). Keep in mind that they might be managing designs of a dozen APIs with different versions. **API Designers don't have time to fiddle with spec formatting. That is not their primary function.** Their task is to keep the family intact, make sure it provides the needed functionality for the business needs and is as easy to use as possible. The above can also be shown as more human understandable visual format. Here's the common and IMHO ugly presentation by default swagger editor: 
+
+<img itemprop="image" src="/assets/img/day71/products.png" alt="{{site.name}}"/>
+
+That would increase the modularity of the design of multiple APIs. This would increase the maintainability of API families a lot. That would increase the design maintainability. Of course if you modify the component, it becomes unique. Modularity loses the value the more you do it. If you would modify each time, you would end up having unique solutions everywhere. As a designer you would be given possibly less freedoms by default and debates regarding design would not be about "standard parameter names" but about making an exception to the rule. 
+