API On-boarding Process: 1st Interview
With empirical studies — prepare to be surprised! Your initial assumption might change drastically.
If you are following our blog, you may already know that Jarkko Moilanen and I are conducting an empirical study on learning experiences of application developers when they are looking for and selecting API/s for implementing a specific system requirement. We have got in touch with developers working in different companies across Finland and already have scheduled upcoming interviews with participants eager and willing enough to share their work process.
The 1st user study was done on 22.08.2017 and initial findings have surprised us. We are reevaluating our assumption to decide whether this is a random scenario or special emphasis should be put in this finding. Time and analysis of future interviews would tell us the answer.
The First Interview
Our user study started with briefly describing about what is API onboarding process and what motivated us for conducting research in such topic. We initially thought about dividing the participants into groups of two. This would have ensured that members are brainstorming to think and project their journey towards finding an API suitable to their system needs before they start using it. However, this user study had only one participant showing up. He works in a well known Finnish software company and has his expertise in API development, developer consultancy and advocacy about open source. After the introductory speech, we requested to show us in pictures or words about his workarounds before he starts using the selected API in his code. We wanted to know details about the following user flows:
- Usual workflow of finding and selecting an existing API suitable to the application requirements.
- Alternatives to the above workflow when such API doesn’t exist.
- How he’d like to go through the process in ideal scenario.
- What would be the ideal scenario of the workflow when no such API exists.
Here are two pictures showing the participant’s described workflow for API onboarding for the above four scenarios.
Here is one of our assumptions that we found, not being the actual case in the very first interview:
API Consumers rely on multiple catalogs to search and select their desired APIs
Usually in the popular API hosting and management platforms like Mashape, IBM, and APInf we see API catalogs as part of their service offerings. However, the participant mentioned that when projects are conducted between the client and the development company, developers usually asks from the client about any in-house APIs of the system they are supposed to use or reference to any 3rd party API vendors when they are discovering the suitable API matching the application requirements. This however depends on the system developers would be working on (e.g. if Google API is used, then there is already a list of products available. Developers simply need to install the product from the Google market place, discover it and learn about the API. Even in this case, developers might still be asking the client for the API.).
The participant also mentioned that usually there is hardly any competition while selecting an API for the specific application need. The case might be different if the developers are building an app about geo-location. There is an google version of suitable API, an open-source mass version, or any other third party APIs. In such case, developers in most cases select the one the client has preference of (e.g. clients having license agreement with different vendors to use their system or API).
Our second assumption was about API documentation:
API documentation would have important role whether that’s rendered API specification, additional documentation or use case examples.
That assumption was crushed partially right from the start. The interviewee did not want to see rendered Swagger or read other documentation — instead he wanted to jump in, ramp up mockup API from machine readable specification and work against it and learn by doing. Sounds very hacker-ish to us! If there’s something tricky in the API, then he would like to see additional documentation.
The participant mentioned that with API definitions available in such format, developers can directly setup their development environment (a.k.a sandbox) and start experimenting with the APIs. Every details about API endpoints, use cases, how to use the API, etc. should be described in the json or yaml files, so that developers don’t need to rely on other form of documentation. If raw API specification is seen as documentation, we are correct in constructing our second assumption. However the method about how it is used is different from our assumption.
At some point of the interview, broadness of API was raised as a topic. The developer said that good APIs should solve specific problems — follow micro-service architecture patterns and thinking.
Ideal pattern
Before wrapping up this blog about the 1st interview, we thought about revealing some insights about an ideal case scenario that the participant would like to follow in his API onboarding process. Participant emphasized about clients having their own API management system with multiple sandboxes, Dashboard and an extensive feedback system.
- The API management system would not only host their in-house developed APIs but also other 3rd party APIs from vendors they have agreements with.
- APIs should be very specific to a particular micro service of a system rather than incorporating all functionality in a single API.
- API management systems should have ready-made, free sandboxes multiple environments like development, QA and production with relevant data available to use. Sandboxes are instances of APIs, so that the real API doesn’t get compromised if some accidents happen. It is also beneficial to have multiple sandboxes so that different vendors exploring the API don’t jeopardize others’ work.
Familiar with Cathedral and Bazaar?
In conclusive remark, we can tell that we might discover different patterns of API on-boarding depending on the work being procured. One possible result is that we end up comparing “company driven” and “community driven” patterns. Which would resemble familiar Cathedral and Bazaar metaphor introduced 1997 by Eric Raymod. The first interview was about the first pattern (Bazaar). The latter is conducted by someone “scratching an itch” (Raymond, 1999) and doing application development without direct monetary benefits or alike (Cathedral).
What the patterns might be eventually is still clouded. Time and results from future interviews should give the guidance to us.
