How do developers learn about APIs?
Breadcrumb
- Home
- PronovixBlog
- How Do Developers Learn About APIs?
In the following article, we invite you to deep-dive into a topic that can help you understand the developer’s world better. This article is a knowledge base that mainly relies on scientific observations, from which we present a summary combined with our experiences. We appreciate both the uniqueness of each individual and the complexity of the developer community as such. The categorization that we present in the following section is a research-based simplification which might serve as an aid to learn about typical patterns observed in the process of API learning. In this article, we will refer to the emerged categories as archetypes.
The contexts for API learning include hobbies, experimentation with technology, completing some minor (e.g. bugfix) or major component of code production, or even owning and developing an API [1]. As diverse as these goals are, so are the developers behind them.
Back in 2007, developers were categorized into three groups based on their approach to learning and coding, with two clearly different groups being the systematic and opportunistic developers, and pragmatic developers having some resemblance to both [2]. The two extremities were observed in scientific research recently [3, 4], indicating that this typology is not something we should forget about.
Systematic developers take a well-educated and defensive approach when coding. They take every precaution they can to protect their code from unstable or untrustworthy processes. These developers amass a deep understanding of technology before using it and pride themselves on building elegant solutions [2].
In the context of API learning, systematic developers will review concepts and architecture documentation to understand the system as a whole and study the individual programming features (e.g. objects, classes, methods and interfaces) to understand how pieces of the system work individually before starting to use them [5].
Since systematic developers will research an API thoroughly before starting a programming task, the act of looking up additional API details later will be a disruption leading to a loss of flow [5]. It is fundamentally important to them to easily locate information in an API reference from the beginning.
Opportunistic developers are curious explorers. They develop just a sufficient understanding of the tech stack to understand how it can solve their current business problem, and delight in solving such problems [2]. They might be highly skillful programmers adopting agile development methods to build applications quickly, or they might be hobby developers or citizen developers (for example scientists writing code to control experiments) [6].
In the context of API learning, they will scan through some of the available documentation pages, check the available tools, and start the task.
On an extreme end, a novice could blindly copy and paste code examples that they find without fully understanding them [7] or even without noticing that the selected code is written in a different code language [8], which would then lead to deleting those parts from the code (since they would not do the job) and starting the whole cycle from the beginning [7]. On a less extreme end, they could try solutions without double-checking in the documentation whether the solutions were correct, and would not follow the processes and suggestions described. They would try things unrelated to the task but possibly helping them build a broader understanding of the API [4].
Often, opportunistic developers will rely on searching the web to find answers rather than resorting to the API documentation on a developer portal or specialized forums. They gather the information they need in parallel to coding, rather than doing one after the other as systematic programmers do [5]. They would do a lot of searches while developing their solution and open many browser tabs as forms of external memory. For this reason, opportunistic developers benefit from organizing their information collections to more easily dismiss or re-find information as their tasks change throughout their coding journey [7] (this could mean grouping browser tabs or pinning favorite documents, etc.)
Their working style combines the elements of the systematic and the opportunistic approaches. They write their code methodically, and develop a sufficient understanding of technology that enables them to use it - but not more (so they don’t necessarily try to understand the bigger picture, or deeply consider the maintainability of the code, etc.). They pride themselves on building robust applications [2].
In the context of API learning, they would learn just enough to start a task and then refer to the documentation and other information resources to solve problems as they encounter them.
These three developer archetypes are more of approaches to learning than personality types. They are also not predetermined by programming skills [2]. Although there might be a preferred and typical approach to learning for a given developer, the same developer might have different approaches on different occasions. Time pressure, future maintenance needs, etc., might affect the way one approaches a problem [6].
Despite the differences outlined above, in some respects all groups have things in common. For example:
Professor Michael Meng and his colleagues have exhaustively researched the topic [3, 4, 6]. According to them, different learners benefit from different features and types of content on a developer portal. Below we highlight some of their guidelines.
Regardless of their approach to work, developers benefit from:
Since systematic developers use a developer portal’s content and features as intended, they benefit from materials explaining the API structure and the rationale behind API design decisions. They also systematically read beginners’ tutorials, and familiarize themselves with the APIs using “Getting Started” documentation.
The opportunistic (and to some extent, the pragmatic) developer deviates from how content is intended to be consumed on the portal. To ensure that their needs are also taken into account, we need to consider the following:
To make the list more exhaustive, we would like to add a few thoughts based on our experience with developer portals.
Developers benefit from a clear and concise API documentation that states language, assumptions and limitations clearly. To reflect on this need, Zero Gravity developer portals allow for both machine-generated code samples and code samples provided by the OpenAPI specification, and they can be easily copied or downloaded by clicking on an icon. In the case of OAS documentation, generated code samples can be available in several programming languages and a selector allows developers to choose the preferred one. Syntax highlighting makes code details easier to understand and transparent. These reduce the risk of copying and pasting code samples that are not a good fit or require much rework to fit the developer’s desired use case.
Clearly outlining all of the possible use cases for an API through documentation or SDKs also benefits developer’s adoption and continued use of your API products. Outlining limitations saves these developers from the work involved in troubleshooting when the API does not in fact meet their expectations or specific requirements. With Zero Gravity developer portals, APIs can be flexibly documented by linking content together and displaying them on different tabs related to the same API. This makes it particularly easy to accommodate use cases, tutorials, examples and the like.
Developers benefit from support, community, and forums because they can ask questions once they have reached the limits of what the documentation (and their own code) allows them to complete. On Zero Gravity portals, developers are supported by FAQs, contact forms, and general documents such as “Get started”. The blog section can be a highlight for the community, especially if members are allowed to showcase their work and solutions.
By anticipating and designing for a diverse audience, you can ensure that developers have a good user experience regardless of their skill level and working style.
Do you need help with your developer portal? If you can use professional help with improving user experience and increasing value for your users, get in touch with us.
All Pronovix publications are the fruit of a team effort, enabled by the research and collective knowledge of the entire Pronovix team. Our ideas and experiences are greatly shaped by our clients and the communities we participate in.
Emese is a UX Researcher at Pronovix. Originally a psychologist with a PhD in cognitive psychology, she has 10 years of experience in scientific research and a passion for data analysis.
Articles on devportals, DX and API docs, event recaps, webinars, and more. Sign up to be up to date with the latest trends and best practices.