Developing successful
business by adapting your products to the diverse global market, relies on quick
and sustainable technical integration. Hence, designing a great interface (API)
is the key for product success today. Classical IT architects, however, don't really care for design, but developer experience people do. I show 5 techniques to design great APIs based on the experience in my last project.
Let me start with a story about the importance of integrated systems for customer experience.
I'm humanistic nerd and triathlete. So, I enjoy to track and analyze my sport performance. I train with a Polar M400 watch and use training plans from the corresponding cloud service Polar Flow. Now, I missed an additional navigation system to not ride the same track all the time and I'd liked to track cadence, which is, unfortunately, not possible with the Polar M400. However, I neither liked the bicycle computer Polar M460, since it's just the features of watch in a bigger housing, nor Polar V650 with big color display. I wanted something simple and lean, which is provided by the Garmin Edge 130. It's a nice small bike computer without touch but b/w display. But, as a result, I had to additionally use the Garmin Connect cloud service to - for example - setup the courses for my navigation system.
I ended up being forced to use two portals -- Polar Flow and Garmin Connect, which I'd liked to interconnect for my training plan. I could have synced it on my mobile with syncmytracks, but this works for Android phones only. So I turned out, that I could not direly connect both cloud services, maybe since they are competitors. But I could connect them via a 3rd platform, i.e. Strava, which did not seem to be considered as competitor. So, all good: I could sync my training data using two devices from different vendors.
As I already wrote, I'm a humanstic nerd. I'm IT architect. Let's have a look at that topic from a technical point of view. This example shows, that all of the involved platforms must be integrated to satisfy me, as the customer. I don't care about the hardware device and I don't care if the vendors are in competition. As a consumer, I care about integrated systems to get my data synchronized. If there is something wrong in the chain of services, I don't care who's fault it is. I'm just not happy.
So being the key for system integration, great interfaces (APIs) are highly important.
In more general words: Developing successful business by adapting your products to the diverse global market, relies on quick and sustainable technical integration. Hence, designing a great interface (API) is the key for product success today.
Serving complex customer needs by combining
your service with others from partners, will allow you to focus on your core
competences and deliver best possible quality. In the last year, I gained experience in this field, since I was lucky to help and enable a great cross functional team of 9 people to grow. We developed a cloud service with API and GUI as well as two mobile apps from scratch and brought it to production stage within just 6 month. It is fully integrated into partner services and apps and it generates business.
In this article, I propose techniques to provide great technical APIs. But let me explain some context first.
APIs (advanced programmable interfaces) provide other services technical interfaces to integrate our service. Our service might offer data and functions of a specific business case. This might be integrated and combined by others service that eventually provide the user interface, like a mobile app that combines our ordering service with another 3rd party service, e.g. payment or user management.
The underlying pattern is “micro-service”. It combines services and reduces the functionality of a service to its core (micro). The downside is: it increases the total number of services, which makes the interconnection API highly important today. And that requires well-designed, great APIs.
However, architects focus in general on strategic feasibility, which is mostly done by trying to change the service as little as possible. But this kills innovation in the sense of extending the service with value generating functions and, moreover, the usability of APIs were less covered. So, APIs are feasible but lack of being valuable and far away from usable (or desirable).
We need API designers who care about integrating the service as a product.
Why do classical architects not care? In my experience, the increasing responsibility of classical senior IT architects (CTOs or Senior engineer) got them to more abstract in thinking (remember the wall-size system landscape diagrams). Furthermore, it does not help that system integration meetings were more like a political fight of experts than a negotiation to accomplish a solution.
Even after exhausting and time consuming discussions, the result was often just a poor implementation with a minimum feature set. The consent is a minimal wrapper service in between, that bridges the gap on just the lowest common denominator regarding features. And this service is often poorly developed, since the added value is not visible for both of the systems individually.
Today, however, the number of service and integration increases due to the pattern of micro-service. This causes even more discussion and the classical approach of high level IT architecture does not scale very well and it does not even cover all necessary aspects of great APIs.
Take an API as a product. We know from product management that a product feature is only as good as its usability: If the user cannot access the feature quickly and easily, she does not get the value and simply stops using it. At the interface to the end user, user experience (UX) designers put effort in designing good user interfaces (UI). Our services do not only face users directly. In the world of highly integrated micro-service, great technical APIs are designed by developer experience (DX).
In order to adapt Marty Cagan's definition of great products (in “How to build products that customers love”), I propose to consider more aspects that just feasibility. A great API should be feasible, desirable (or usable) and valuable.
This can be done by a triangle of the following responsibilities and corresponding roles
This three goals might be contradictory. To develop great APIs, you would want to find the right balance between functional requirements (product) and non-functional-requirements (architecture) between short-term and long-term aspects (product vision and architecture vision). To bring all aspects to the table, I suggest to split the responsibilities to roles of different people and establish a healthy culture which allows open and honest discussion based on a reliable personal relation.
Although this organizational blueprint might the team develop great APIs and help to integrate and make your product successful, it strongly depends on the people’s ability for team work. Other than that, I discovered some basic techniques to bring a great API to live.
To get yourself into the consumers position, write a test service against your own API and really work with it. The drawback of this approach is, that you might simplify the test for laziness. In order to avoid that, you might ask a colleague to do that for you and offer it to her in exchange.
Implement not just automated integration tests (with e.g. postman). Instead, run user tests by putting your own GUI on top of the APIs and really use it. Get yourself into the consumers perspective and ask yourself: What would I say as a developer who must integrate that service? If you cannot do it, ask your customers for feedback.
Don’t be over specific. Don’t limit the design, just because you could define it: If you don’t need to limit the length of the datatype, because your database doesn’t care, why would you want to define it at the API. If it’s for security reasons, work on the security not on the data types.
Document features beyond CRUD, such as aggregations, grouping or any calculation, well.
API documentation must be immediately done by the developers to reduce the risk of Chinese whispers. There is no business consultant needed as man in the middle. API documentation is written for developers, so why not ask developers to write it. They know the relevant information and they’ll drop the irrelevant, since developers (at least the developers I know) like spending time on implementation better than on documentation. To make documentation good, make it easy to do: automate as much as you can. Built it automatically with the code in your CI/CD pipeline and use visualization tools, such as swagger.
Write everything for production stage. Better implement slim than fat. Keep it clean. Although it might be a tiny feature, once it’s done, it’s done done – and you never have to reimplement it. Hence, developers can focus on the next thing.
As a result, clean architecture gives you flexibility in further developing the service, internally and externally via the API.
Consider your customer as your partner and develop the interface as if you would do it for yourself. Why would you implement features just for internal usage and hide it to others. And you might get a unique and stable implementation of your API.
Just adding functionality let the system become big and big systems are slowly developed. Many dependencies lead to complexity and exhausting architecture discussions and this makes it hard to add new features. In order to avoid that, you need to keep the number of features small by either not developing them (lean) or removing them, once they do not generate value. A feature does not generate any value, if it is not used. So monitor the usage of the features of your service. And take decisions based on that numbers.
If you accumulate the numbers and deduce how consumers use your system, you can adapt your payment and business model. You could compare if the user better pay by account, by traffic or by feature. How cool is that?!
Due to my experience, a great API is developed and sustainably maintained by focusing on only the minimum valuable feature set, easy-to-use solutions, simple implementations with respect to the consumer’s eyes and the ability to continually adapt your API based on real numbers.
Let me start with a story about the importance of integrated systems for customer experience.
I'm humanistic nerd and triathlete. So, I enjoy to track and analyze my sport performance. I train with a Polar M400 watch and use training plans from the corresponding cloud service Polar Flow. Now, I missed an additional navigation system to not ride the same track all the time and I'd liked to track cadence, which is, unfortunately, not possible with the Polar M400. However, I neither liked the bicycle computer Polar M460, since it's just the features of watch in a bigger housing, nor Polar V650 with big color display. I wanted something simple and lean, which is provided by the Garmin Edge 130. It's a nice small bike computer without touch but b/w display. But, as a result, I had to additionally use the Garmin Connect cloud service to - for example - setup the courses for my navigation system.
I ended up being forced to use two portals -- Polar Flow and Garmin Connect, which I'd liked to interconnect for my training plan. I could have synced it on my mobile with syncmytracks, but this works for Android phones only. So I turned out, that I could not direly connect both cloud services, maybe since they are competitors. But I could connect them via a 3rd platform, i.e. Strava, which did not seem to be considered as competitor. So, all good: I could sync my training data using two devices from different vendors.
As I already wrote, I'm a humanstic nerd. I'm IT architect. Let's have a look at that topic from a technical point of view. This example shows, that all of the involved platforms must be integrated to satisfy me, as the customer. I don't care about the hardware device and I don't care if the vendors are in competition. As a consumer, I care about integrated systems to get my data synchronized. If there is something wrong in the chain of services, I don't care who's fault it is. I'm just not happy.
So being the key for system integration, great interfaces (APIs) are highly important.
In more general words: Developing successful business by adapting your products to the diverse global market, relies on quick and sustainable technical integration. Hence, designing a great interface (API) is the key for product success today.
In this article, I propose techniques to provide great technical APIs. But let me explain some context first.
Micro-Service architecture requires great technical APIs.
Today, services to the consumer are interconnected network of sub-services. Hence, great APIs are highly important to easily and quickly integrate services.APIs (advanced programmable interfaces) provide other services technical interfaces to integrate our service. Our service might offer data and functions of a specific business case. This might be integrated and combined by others service that eventually provide the user interface, like a mobile app that combines our ordering service with another 3rd party service, e.g. payment or user management.
The underlying pattern is “micro-service”. It combines services and reduces the functionality of a service to its core (micro). The downside is: it increases the total number of services, which makes the interconnection API highly important today. And that requires well-designed, great APIs.
Developer experience (DX) is designing APIs.
Since API design seemed to be complicated stuff to designers and product people, historically, APIs were designed by senior developers or technical architects, who – by nature – focus on non-functional requirement, such as backwards compatibility for maintainability. Modern architects may also care for things like simplicity for scale in cloud environments or energy consumption on mobile devices.However, architects focus in general on strategic feasibility, which is mostly done by trying to change the service as little as possible. But this kills innovation in the sense of extending the service with value generating functions and, moreover, the usability of APIs were less covered. So, APIs are feasible but lack of being valuable and far away from usable (or desirable).
We need API designers who care about integrating the service as a product.
Why do classical architects not care? In my experience, the increasing responsibility of classical senior IT architects (CTOs or Senior engineer) got them to more abstract in thinking (remember the wall-size system landscape diagrams). Furthermore, it does not help that system integration meetings were more like a political fight of experts than a negotiation to accomplish a solution.
Even after exhausting and time consuming discussions, the result was often just a poor implementation with a minimum feature set. The consent is a minimal wrapper service in between, that bridges the gap on just the lowest common denominator regarding features. And this service is often poorly developed, since the added value is not visible for both of the systems individually.
Today, however, the number of service and integration increases due to the pattern of micro-service. This causes even more discussion and the classical approach of high level IT architecture does not scale very well and it does not even cover all necessary aspects of great APIs.
Take an API as a product. We know from product management that a product feature is only as good as its usability: If the user cannot access the feature quickly and easily, she does not get the value and simply stops using it. At the interface to the end user, user experience (UX) designers put effort in designing good user interfaces (UI). Our services do not only face users directly. In the world of highly integrated micro-service, great technical APIs are designed by developer experience (DX).
Cross functional teams with DX provide great APIs
Since technical APIs get more important and we already know the importance of good design from UX, Developer experience (DX) takes the responsibly for good technical APIs. Just like UX designers for user interfaces, the DX designers covers usable and desirable technical interfaces. Experience designer (XD) combine both.In order to adapt Marty Cagan's definition of great products (in “How to build products that customers love”), I propose to consider more aspects that just feasibility. A great API should be feasible, desirable (or usable) and valuable.
This can be done by a triangle of the following responsibilities and corresponding roles
- Valuable - Product Owner (PO)
- Desirable - Experience designer (XD)
- Feasible - Developer
This three goals might be contradictory. To develop great APIs, you would want to find the right balance between functional requirements (product) and non-functional-requirements (architecture) between short-term and long-term aspects (product vision and architecture vision). To bring all aspects to the table, I suggest to split the responsibilities to roles of different people and establish a healthy culture which allows open and honest discussion based on a reliable personal relation.
Although this organizational blueprint might the team develop great APIs and help to integrate and make your product successful, it strongly depends on the people’s ability for team work. Other than that, I discovered some basic techniques to bring a great API to live.
Techniques for implementing desirable, feasible and valuable APIs
Great APIs are feasible, valuable and desirable. You allow others to quickly and simply re-/integrate your service by- Seeing your service through the consumer’s eyes.
- Building lean feature sets to profitably generate value while staying flexible.
- Producing usable solutions to enable quick system integration.
- Generating feasible implementation to reduce system complexity and, thus, increases flexibility to change.
- Build-measure-learn to continuously redesign your API and business.
1. See your service through the consumer’s eyes.
As a developer, I’m interested in how to implement a feature. However, a consumer is not interested in that. She is not interested in the things behind the API. She is interested in using the API, which means quickly integrating the API into their service. And that’s it, although she is also a developer.To get yourself into the consumers position, write a test service against your own API and really work with it. The drawback of this approach is, that you might simplify the test for laziness. In order to avoid that, you might ask a colleague to do that for you and offer it to her in exchange.
Implement not just automated integration tests (with e.g. postman). Instead, run user tests by putting your own GUI on top of the APIs and really use it. Get yourself into the consumers perspective and ask yourself: What would I say as a developer who must integrate that service? If you cannot do it, ask your customers for feedback.
2. Build a lean product APIs.
Few functions reduce backward compatibility issues (- your architects will love it). And just the most important features are profitable. Features with low value, however, will not withhold your customers to buy your product. So just implement the functions with high value to the customer and remove everything that is not used. Unfortunately, no product manager can predict the future. So use numbers to prove usage. Implement prototypes and test it with real users, once you are convinced about the business value, get it integrate it into your services. If you gain no value, drop the feature, document your decision and leave it there. Don’t try to develop a jackalope. And design the API close to your product features.3. Usable solutions are easy to understand.
Utilize standard technology start with implementing the standard functions, such as CRUD (Create, Read, Update, Delete) operation with HTTP and JSON. Hence, (almost) everybody will know how to use it.Don’t be over specific. Don’t limit the design, just because you could define it: If you don’t need to limit the length of the datatype, because your database doesn’t care, why would you want to define it at the API. If it’s for security reasons, work on the security not on the data types.
Document features beyond CRUD, such as aggregations, grouping or any calculation, well.
API documentation must be immediately done by the developers to reduce the risk of Chinese whispers. There is no business consultant needed as man in the middle. API documentation is written for developers, so why not ask developers to write it. They know the relevant information and they’ll drop the irrelevant, since developers (at least the developers I know) like spending time on implementation better than on documentation. To make documentation good, make it easy to do: automate as much as you can. Built it automatically with the code in your CI/CD pipeline and use visualization tools, such as swagger.
4. Feasible implementation are based on simple concepts.
Follow KISS. Implement as simple as possible. Simplicity is hard to design. So put high effort in design. Define the structure of your technical interface close to your database model with CRUD operations and few methods on top. Why would you want to make it complicated?Write everything for production stage. Better implement slim than fat. Keep it clean. Although it might be a tiny feature, once it’s done, it’s done done – and you never have to reimplement it. Hence, developers can focus on the next thing.
As a result, clean architecture gives you flexibility in further developing the service, internally and externally via the API.
Consider your customer as your partner and develop the interface as if you would do it for yourself. Why would you implement features just for internal usage and hide it to others. And you might get a unique and stable implementation of your API.
5. Build-measure-learn to continuously redesign your API and reshape business.
The techniques above consider criteria for good APIs. This last one is about the process building it, more precisely the continuous process of rebuilding it.Just adding functionality let the system become big and big systems are slowly developed. Many dependencies lead to complexity and exhausting architecture discussions and this makes it hard to add new features. In order to avoid that, you need to keep the number of features small by either not developing them (lean) or removing them, once they do not generate value. A feature does not generate any value, if it is not used. So monitor the usage of the features of your service. And take decisions based on that numbers.
If you accumulate the numbers and deduce how consumers use your system, you can adapt your payment and business model. You could compare if the user better pay by account, by traffic or by feature. How cool is that?!
Summary
Setting up a network of service with the Micro-services architecture is a great approach to generate customer value, as the example of sports activity tracking services showed. It requires developing great API to easily integrate your service into others. Great APIs are valuable, feasible and desirable to other developers, who need to simply integrate and use your APIs. To avoid high level architecture discussion, a cross-functional team with a developer experience (DX) designer shares the responsibility of the three aspects for great APIs: Valuable by Product Owner, Desirable by Experience Designer, Feasibility by developer.Due to my experience, a great API is developed and sustainably maintained by focusing on only the minimum valuable feature set, easy-to-use solutions, simple implementations with respect to the consumer’s eyes and the ability to continually adapt your API based on real numbers.
Kommentare
Kommentar veröffentlichen