mirror of
https://github.com/twirl/The-API-Book.git
synced 2025-04-23 11:07:53 +02:00
Proofreading
This commit is contained in:
Sergey Konstantinov
parent
66858e58b1
commit
d296937e62
BIN
docs/API.en.epub
BIN
docs/API.en.epub
Binary file not shown.
@ -5799,93 +5799,93 @@ do {
|
||||
</li>
|
||||
</ol>
|
||||
<p>Sometimes providing APIs is a method to “probe the ground,” i.e., to evaluate the market and decide whether it's worth having a full-scale user service there. (We rather condemn this practice as it inevitably leads to discontinuing the API or limiting its functionality, either because the market turns out to be not as profitable as expected, or because the API eventually becomes a competitor to the main service.)</p><div class="page-break"></div><h3><a href="#api-product-vision" class="anchor" id="api-product-vision">Chapter 53. Developing a Product Vision</a><a href="#chapter-53" class="secondary-anchor" id="chapter-53"> </a></h3>
|
||||
<p>The above-mentioned fragmentation of the API target audience, i.e., the “developers — business — end users” triad, makes API product management quite a non-trivial problem. Yes, the basics are the same: find your audience's needs and satisfy them; the problem is that your product has several different audiences, and their interests sometimes diverge. The end users' request for an affordable cup of coffee does not automatically imply business demand for a coffee machine API.</p>
|
||||
<p>The above-mentioned fragmentation of the API target audience, i.e., the “developers — business — end users” triad, makes API product management quite a non-trivial problem. Yes, the basics are the same: find your audience's needs and satisfy them. The problem is that your product has several different audiences, and their interests sometimes diverge. The end users' request for an affordable cup of coffee does not automatically imply business demand for a coffee machine API.</p>
|
||||
<p>Generally speaking, the API product vision must include the same three elements:</p>
|
||||
<ul>
|
||||
<li>Grasping how <em>end users</em> would like to have their problems solved</li>
|
||||
<li>Projecting how <em>businesses</em> would solve those problems if appropriate tools existed</li>
|
||||
<li>Understanding what technical solutions for <em>developers</em> might exist to help them implement the functionality businesses would ask for, and where are the boundaries of their applicability.</li>
|
||||
<li>Understanding what technical solutions for <em>developers</em> might exist to help them implement the functionality businesses would ask for, and where the boundaries of their applicability lie.</li>
|
||||
</ul>
|
||||
<p>In different markets and different situations, the “weight” of each element differs. If you're creating an API-first product for developers with no UI components, you might skip the end users' problems analysis; and, by contrast, if you're providing an API to extremely valuable functionality and you're holding a close-to-monopolistic position on the market, you might actually never care about how developers love your software architecture or how convenient your interfaces are for them — as they simply have no other choice.</p>
|
||||
<p>In different markets and different situations, the “weight” of each element differs. If you're creating an API-first product for developers with no UI components, you might skip the end users' problem analysis. On the other hand, if you're providing an API with extremely valuable functionality and you hold a close-to-monopolistic position in the market, you might actually not care about how developers love your software architecture or the convenience of your interfaces for them, as they simply have no other choice.</p>
|
||||
<p>Still, in the majority of cases, we have to deal with two-step heuristics based on either technical capabilities or business demands:</p>
|
||||
<ul>
|
||||
<li>You might first form the vision of how you might help business owners given the technical capabilities you have (heuristics step one). Then, the general vision of how your API will be used to satisfy end users' needs (heuristics step two), or</li>
|
||||
<li>Given your understanding of business owners' problems, you might make one heuristic “step right” to outline future functionality for end users and one “step left” to evaluate possible technical solutions.</li>
|
||||
<li>You might first form the vision of how you can help business owners given the technical capabilities you have (heuristics step one) then develop a general vision of how your API will be used to satisfy end users' needs (heuristics step two), or</li>
|
||||
<li>Given your understanding of business owners' problems, you can take one heuristic “step right” to outline future functionality for end users and one “step left” to evaluate possible technical solutions.</li>
|
||||
</ul>
|
||||
<p>As both approaches are still heuristic, the API product vision is inevitably fuzzy, and it's rather normal: if you could have got a full and clear understanding of what end-user products might be developed on top of your API, you might have developed them on your own behalf, skipping intermediary agents. It is also important to keep in mind that many APIs pass the “terraforming” stage (see the previous chapter) thus preparing the ground for new markets and new types of services — so your idealistic vision of a nearby future where delivering freshly brewed coffee by drones will be a norm of life is to be refined and clarified while new companies providing new kinds of services are coming to the market. (Which in its turn will make an impact on the monetization model: detailing the countenance of the forthcoming will make your abstract KPIs and theoretical benefits of having an API more and more concrete.)</p>
|
||||
<p>The same fuzziness should be kept in mind while making interviews and getting feedback. Software engineers will mainly report the problems they've got with the technical integrations, and rarely speak of business-related issues; meanwhile, business owners care little about the inconvenience of writing code. Both will have some knowledge regarding the end users' problems, but it's usually limited to the market segment the partner operates on.</p>
|
||||
<p>If you do have an access to end users' actions monitoring (see “<a href="#api-product-kpi">The API Key Performance Indicators</a>” chapter), then you might try to analyze the typical user behavior through these logs and understand how users interact with the partners' applications. But you will need to make this analysis on a per-application basis and try to clusterize the most common scenarios.</p>
|
||||
<p>Since both approaches are still heuristic, the API product vision is inevitably fuzzy, and that's quite normal. If you had a full and clear understanding of what end-user products could be developed on top of your API, you might have developed them yourself, bypassing intermediary agents. It is also important to keep in mind that many APIs go through the “terraforming” stage (see the previous chapter), preparing the ground for new markets and new types of services. Therefore, your idealistic vision of a nearby future where delivering freshly brewed coffee by drones becomes the norm of life is to be refined and clarified as new companies providing new kinds of services enter the market. (This, in turn, will impact monetization models as detailing the countenance of the forthcoming will make your abstract KPIs and theoretical benefits of having an API more and more concrete.)</p>
|
||||
<p>The same fuzziness should be kept in mind when conducting interviews and gathering feedback. Software engineers will mainly report problems they encountered during technical integrations and rarely discuss business-related issues. Meanwhile, business owners care little about the inconvenience of writing code. Both groups will have some knowledge regarding end users' problems, but it's usually limited to the market segment in which the partner operates.</p>
|
||||
<p>If you do have access to end users' action monitoring (see “<a href="#api-product-kpi">The API Key Performance Indicators</a>” chapter), you can try to analyze typical user behavior through these logs and understand how users interact with the partners' applications. However, you will need to conduct this analysis on a per-application basis and attempt to clusterize the most common scenarios.</p>
|
||||
<h4>Checking Product Hypotheses</h4>
|
||||
<p>Apart from the general complexity of formulating the product vision, there are also tactical issues with checking product hypotheses. “The Holy Grail” of product management — that is, creating a cheap (in terms of resource spent) minimal viable product (MVP) — is normally unavailable for an API product manager. The thing is that you can't easily <em>test</em> the solution even if you managed to develop an API MVP: to do so, partners are to <em>develop some code</em>, i.e., invest their money; and if the outcome of the experiment is negative (meaning that the further development looks unpromising), this money will be wasted. Of course, partners will be a little bit skeptical towards such proposals. Thus a “cheap” MVP should include either the compensation for partners' expenses or the budget to develop a reference implementation (i.e., a complementary application that is created to support the API MVP).</p>
|
||||
<p>You might partially solve the problem by making some third-party company release the MVP (for example, in a form of an open-source module published in some developer's personal repository) but then you will struggle with hypothesis validation issues as such modules might easily go unnoticed.</p>
|
||||
<p>Another option for checking conjectures is recruiting some other developers within the API provider company to try the API in their services. Internal customers are usually much more loyal towards spending some effort to check a hypothesis, and it's much easier to negotiate MVP curtailing or freezing with them. The problem is that you can check only those ideas that are relevant to the company's internal needs.</p>
|
||||
<p>Also, applying the “eat your own dog food” concept to APIs means that the API product team should have their own test applications (so-called “pet projects”) on top of the API. Given the complexity of developing such applications, it makes sense to encourage having them, e.g., by giving free API quotas to team members and providing sufficient free computational resources.</p>
|
||||
<p>Such pet projects are also valuable because of the unique experience they allow to gain: everyone might try a new role. Developers will learn product managers' typical problems: it's not enough to write fine code, you also need to know your customer, understand their demands, formulate an attractive concept, and communicate it. In their turn, product managers will get some understanding of how exactly easy or hard it is to render their product vision into life, and what problems the implementation will bring. Finally, both will benefit from taking a fresh look at the API documentation and putting themselves in the shoes of a developer who heard about the API product for the first time and is now struggling with grasping the basics.</p><div class="page-break"></div><h3><a href="#api-product-devrel" class="anchor" id="api-product-devrel">Chapter 54. Communicating with Developers</a><a href="#chapter-54" class="secondary-anchor" id="chapter-54"> </a></h3>
|
||||
<p>As we have described in the previous chapters, managing an API product requires building relations with both business partners and developers. (Ideally, with end users as well; though this option is seldom available to API providers.)</p>
|
||||
<p>Let's start with developers. The specifics of software engineers as an audience are the following:</p>
|
||||
<p>In addition to the general complexity of formulating the product vision, there are also tactical issues with checking product hypotheses. “The Holy Grail” of product management — creating a cheap (in terms of resource expenditure) minimal viable product (MVP) — is typically unavailable for an API product manager. The reason is that you can't easily <em>test</em> the solution even if you manage to develop an API MVP. To do so, partners would need to <em>develop an application</em>, i.e., invest their money. If the outcome of the experiment is negative, meaning that further development appears unpromising, this money will be wasted. Of course, partners will be a little bit skeptical towards such proposals. Therefore, a “cheap” MVP should include either compensation for partners' expenses or a budget to develop a reference implementation (i.e., a complementary application specifically developed to support the API MVP).</p>
|
||||
<p>You can partially address the problem by having a third-party company release the MVP, for example, in the form of an open-source module published in a developer's personal repository. However, you will struggle with hypothesis validation issues as such modules might easily go unnoticed.</p>
|
||||
<p>Another option for checking conjectures is recruiting other developers within the API provider company to try the API in their services. Internal customers are usually much more loyal towards spending some effort to check a hypothesis, and it's much easier to negotiate MVP curtailing or freezing with them. The problem is that you can only validate those ideas that are relevant to the company's internal needs.</p>
|
||||
<p>Also, applying the “eat your own dog food” concept to APIs means that the API product team should have their own test applications (so-called “pet projects”) on top of the API. Given the complexity of developing such applications, it makes sense to encourage having them, for example, by giving free API quotas to team members and providing sufficient free computational resources.</p>
|
||||
<p>Such pet projects are also valuable because of the unique experience they allow to gain: everyone might try a new role. Developers will learn about product managers' typical problems: it's not enough to write good code, you also need to know your customer, understand their demands, formulate an attractive concept, and effectively communicate it. On the other hand, product managers will gain understanding of how exactly easy or hard it is to bring their product vision to life and what challenges they may face. Finally, both groups will benefit from taking a fresh look at the API documentation and putting themselves in the shoes of a developer who is hearing about the API product for the first time and struggling to grasp the basics.</p><div class="page-break"></div><h3><a href="#api-product-devrel" class="anchor" id="api-product-devrel">Chapter 54. Communicating with Developers</a><a href="#chapter-54" class="secondary-anchor" id="chapter-54"> </a></h3>
|
||||
<p>As we have described in the previous chapters, managing an API product requires building relationships with both business partners and developers. (Ideally, with end users as well, although this option is seldom available to API providers.)</p>
|
||||
<p>Let's start with developers. The specifics of software engineers as an audience are as follows:</p>
|
||||
<ul>
|
||||
<li>Developers are highly-educated individuals with practical thinking; as a rule, they choose technical products with extreme rationality (unless you're giving them cool backpacks with fancy prints for free).
|
||||
<li>Developers are highly educated individuals with practical thinking. As a rule, they choose technical products with extreme rationality (unless you're giving them cool backpacks with fancy prints for free).
|
||||
<ul>
|
||||
<li>This doesn't prevent them from having a certain aptitude towards, let's say, specific programming languages or frameworks; however, <em>affecting</em> those aptitudes is extremely hard and is normally not in the API vendor's power.</li>
|
||||
<li>This doesn't prevent them from having a certain aptitude towards, let's say, specific programming languages or frameworks; however, <em>influencing</em> those aptitudes is extremely hard and is normally not within the API vendor's power.</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>In particular, developers are quite skeptical towards promotional materials and overstatements and are ready to actually check whether your claims are true.</li>
|
||||
<li>It is very hard to communicate to them via regular marketing channels; they get information from highly specialized communities, and they stick to opinions proved by concrete numbers and examples (ideally, code samples).
|
||||
<li>Developers are quite skeptical towards promotional materials and overstatements. They are ready to actually check whether your claims are true.</li>
|
||||
<li>It is very hard to communicate with developers via regular marketing channels. They get information from highly specialized communities and they stick to opinions proved by concrete numbers and examples (ideally, code samples).
|
||||
<ul>
|
||||
<li>The “influencers” words are not very valuable to them, as no opinions are trusted if unsubstantiated.</li>
|
||||
<li>The words of “influencers” are not very valuable to them, as no opinions are trusted if unsubstantiated.</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>The Open Source and free software ideas are widespread among developers If you try to make money out of things that must be free and/or open from their point of view (for example, by proclaiming interfaces an intellectual property), you will face resistance (and views on this “musts”… differ).</li>
|
||||
<li>The ideas of open source and free software are widespread among developers If you try to make money out of things that they believe should be free and/or open (for example, by proclaiming interfaces as intellectual property), you will face resistance (and views on these “shoulds” differ).</li>
|
||||
</ul>
|
||||
<p>Because of the above-mentioned specifics (first of all, the relative insignificance of influencers and the critical attitude towards promotions), you will have to communicate to developers via very specific media:</p>
|
||||
<p>Because of the aforementioned specifics (especially the relative insignificance of influencers and the critical attitude towards promotions), you will have to communicate to developers via very specific media:</p>
|
||||
<ul>
|
||||
<li>Collective blogs (like the “r/programming” subreddit or dev.to)</li>
|
||||
<li>Q&A sites (StackOverflow, Experts Exchange)</li>
|
||||
<li>Educational services (CodeAcademy, Udemy)</li>
|
||||
<li>Q&A sites (Stack Overflow, Experts Exchange)</li>
|
||||
<li>Educational services (Codecademy, Udemy)</li>
|
||||
<li>Technical conferences and webinars.</li>
|
||||
</ul>
|
||||
<p>In all these channels, the direct advertising of your API is either problematic or impossible. (Well, strictly speaking, you may buy the banner on one of the sites advertising the advantages of your API, but we hardly doubt it will improve your relations with developers.) You need to generate some valuable and/or interesting content for them, which will improve the knowledge of your API. And this is the job for your developers: writing articles, answering questions, recording webinars, and giving pitches.</p>
|
||||
<p>Developers do like sharing the experience, and will probably be eager to do it — during their work hours. A proper conference talk, let alone an educational course, requires a lot of preparation time. Out of this book's author's experience, two things are crucial for tech-PR:</p>
|
||||
<p>In all these channels, direct advertising of your API is either problematic or impossible. (Well, strictly speaking, you may buy a banner on one of the sites advertising the advantages of your API, but we highly doubt it will improve your relations with developers.) You need to generate valuable and/or interesting content for them, which will improve their knowledge of your API. And this is the job for your developers: writing articles, answering questions, recording webinars, and giving pitches.</p>
|
||||
<p>Developers enjoy sharing their experiences and will probably be eager to do so — during their work hours. A proper conference talk, let alone an educational course, requires a lot of preparation time. From this book's author's experience, two things are crucial for tech PR:</p>
|
||||
<ul>
|
||||
<li>Incentives, even nominal ones — the job of promoting a product should be rewarded</li>
|
||||
<li>Methodicalness and quality standards — you might actually do the content review just like you do the code review.</li>
|
||||
<li>Methodicalness and quality standards — you might actually do content review just like you do code review.</li>
|
||||
</ul>
|
||||
<p>Nothing could make the worse counter-advertising for your product than a poorly prepared pitch (as we said, the mistakes will be inevitably found and pointed to) or a badly camouflaged commercial in a form of a pitch (the reason is actually the same). Texts are to be worked upon: pay attention to the structure, logic, and tempo of the narration. Even a technical story must be finely constructed; after it's ended, the listeners must have a clear understanding of what idea you wanted to communicate (and it'd rather be somehow coupled with your API's fitness for their needs).</p>
|
||||
<p>A word on “evangelists” (those are people who have some credibility in the IT community and work on promoting a technology or a tech company, being a company's contractor or even a staff member, effectively carrying out all those above-mentioned activities like blog-posting, course-preparing, conference-speaking, etc.) Having an evangelist makes the API development team exempt from the necessity of performing the tech-PR. However, we would rather advise having this expertise inside the team, as direct interaction with developers helps with forming the product vision. (That doesn't mean the evangelists are not needed at all - you might well combine these two strategies.)</p>
|
||||
<p>Nothing could be worse counter-advertising for your product than a poorly prepared pitch (as we said, mistakes will inevitably be found and pointed out) or a badly camouflaged commercial in the form of a pitch (the reason is actually the same). Texts need to be worked upon: pay attention to the structure, logic, and tempo of the narration. Even a technical story must be finely constructed; after it's ended, the listeners must have a clear understanding of the idea you wanted to communicate (and it should rather be linked with your API's fitness for their needs).</p>
|
||||
<p>A word on “evangelists” (those are people who have credibility in the IT community and work on promoting a technology or a tech company, either as a company's contractor or even a staff member, effectively carrying out all those aforementioned activities, such as blog posting, course preparing, conference speaking, etc.) Having an evangelist makes the API development team exempt from the necessity of performing tech PR. However, we would rather advise having this expertise inside the team, as direct interaction with developers helps in forming the product vision. (That doesn't mean evangelists are not needed at all - you might well combine these two strategies.)</p>
|
||||
<h4>Open Source</h4>
|
||||
<p>The important question which sooner or later will stand in any API vendor's way is making the source code open. This decision has both advantages and disadvantages:</p>
|
||||
<p>The important question that will sooner or later arise for any API vendor is whether to make the source code open. This decision has both advantages and disadvantages:</p>
|
||||
<ul>
|
||||
<li>You will improve the knowledge of the brand, and some respect will be paid to you by the IT community.
|
||||
<ul>
|
||||
<li>That's given your code is finely written and commented.</li>
|
||||
<li>Given that your code is finely written and commented.</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>You will get some additional feedback — ideally, pull requests from third-party developers
|
||||
<li>You will receive some additional feedback, ideally in the form of pull requests from third-party developers.
|
||||
<ul>
|
||||
<li>And you will also get a number of inquiries and comments ranging from useless to obviously provocative ones, to which you will have to respond politely.</li>
|
||||
<li>You will also receive a number of inquiries and comments ranging from useless to obviously provocative ones, to which you will have to respond politely.</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>Donating code to open source makes developers trust the company more, and affects their readiness to rely on the platform.
|
||||
<ul>
|
||||
<li>But it also increases risks, both from the information security point of view and from the product one, as a dissatisfied community might fork your repo and create a competing product.</li>
|
||||
<li>However, it also increases risks, both from an information security point of view and in terms of the product, as a dissatisfied community might fork your repository and create a competing product.</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
<p>Finally, just the preparations to make the code open might be very expensive: you need to clean the code, switch to open building and testing tools, and remove all references to proprietary resources. This decision is to be made very cautiously, after having all pros and cons elaborated over. We might add that many companies try to reduce the risks by splitting the API code into two parts, the open one and the proprietary one, and also by selecting a license that disallows harming the company's interests by using the open-sourced code (for example, by prohibiting selling hosted solutions or by requiring the derivative works to be open-sourced as well).</p>
|
||||
<p>Finally, just the preparations to make the code open might be very expensive. You need to clean the code, switch to open building and testing tools, and remove all references to proprietary resources. This decision is to be made very cautiously after considering all pros and cons. We might add that many companies try to reduce the risks by splitting the API code into two parts: the open one and the proprietary one. Additionally, the risks could be mitigated by selecting a license that disallows harming the company's interests by using the open-sourced code (for example, by prohibiting selling hosted solutions or by requiring the derivative works to be open-sourced as well).</p>
|
||||
<h4>The Audience Fragmentation</h4>
|
||||
<p>There is one very important addition to the discourse: as informational technologies are universally in great demand, a significant percentage of your customers will not be professional software engineers. A huge number of people are somewhere on the track of mastering the occupation: someone is trying to write code in addition to the basic duties, another one is being retrained now, and the third one is studying the basics of computer science on their own. Many of those non-professional developers make a direct impact on the process of selecting an API vendor — for example, small business owners who additionally seek to automate some routine tasks programmatically.</p>
|
||||
<p>It will be more correct if we say that you're actually working for two main types of audiences:</p>
|
||||
<p>There is one very important addition to the discourse: as information technologies are universally in great demand, a significant percentage of your customers will not be professional software engineers. A huge number of people are somewhere on the path to mastering the occupation. Some are trying to write code in addition to the basic duties, others are undergoing retraining, and some are studying the basics of computer science on their own. Many of these non-professional developers have a direct impact on the process of selecting an API vendor, such as small business owners who seek to automate routine tasks programmatically.</p>
|
||||
<p>It would be more accurate to say that API providers are actually working for two main types of audiences:</p>
|
||||
<ul>
|
||||
<li>Beginners and amateurs, for whom each of those integration tasks would be completely new and unexplored territory</li>
|
||||
<li>Beginners and amateurs, for whom each integration task would be completely new and unexplored territory</li>
|
||||
<li>Professional developers who possess vast experience in integrating different third-party systems.</li>
|
||||
</ul>
|
||||
<p>This fact greatly affects everything we had discussed previously (except for, maybe, open-sourcing, as amateur developers pay little attention to it):</p>
|
||||
<p>This fact greatly affects everything we discussed previously (except for, perhaps, open-sourcing, as amateur developers pay little attention to it):</p>
|
||||
<ul>
|
||||
<li>Your pitches, webinars, lectures, etc., must somehow fit both professional and semi-professional audiences.</li>
|
||||
<li>A huge share of customers' inquiries to your customer support service will be generated by the first category of developers: it's much harder for amateurs or beginners to find answers to their questions by themselves, and they will address them to you.</li>
|
||||
<li>Your pitches, webinars, lectures, etc., must somehow cater to both professional and semi-professional audiences.</li>
|
||||
<li>A significant share of inquiries to your customer support service will be generated by the first category of developers. It is much harder for amateurs or beginners to find answers to their questions by themselves, and they will reach out to you for assistance.</li>
|
||||
<li>At the same time, the second category is much more sensitive to the quality of both the product and customer support, and fulfilling their requests might be non-trivial.</li>
|
||||
</ul>
|
||||
<p>Finally, it's almost impossible in a course of a single product to create an API that will fit well both amateur and professional developers: the former need the maximum simplicity of implementing basic use cases, while the latter seek the ability to adapt the API to match technological stack and development paradigms, and the problems they solve usually require deep customization. We will discuss the matter in “<a href="#api-product-range">The API Services Range</a>” chapter.</p><div class="page-break"></div><h3><a href="#api-product-business-comms" class="anchor" id="api-product-business-comms">Chapter 55. Communicating with Business Owners</a><a href="#chapter-55" class="secondary-anchor" id="chapter-55"> </a></h3>
|
||||
<p>Finally, it is almost impossible to create an API that will suit both amateur and professional developers well within a single product. The former need maximum simplicity in implementing basic use cases, while the latter seek the ability to adapt the API to match their technological stack and development paradigms and the problems they solve usually require deep customization. We will discuss this matter in the “<a href="#api-product-range">API Services Range</a>” chapter.</p><div class="page-break"></div><h3><a href="#api-product-business-comms" class="anchor" id="api-product-business-comms">Chapter 55. Communicating with Business Owners</a><a href="#chapter-55" class="secondary-anchor" id="chapter-55"> </a></h3>
|
||||
<p>The basics of interacting with business partners are to some extent paradoxically contrary to the basics of communicating with developers:</p>
|
||||
<ul>
|
||||
<li>On one hand, partners are much more loyal and sometimes even enthusiastic regarding opportunities you offer (especially free ones).</li>
|
||||
|
||||
BIN
docs/API.en.pdf
BIN
docs/API.en.pdf
Binary file not shown.
BIN
docs/API.ru.epub
BIN
docs/API.ru.epub
Binary file not shown.
@ -5676,8 +5676,8 @@ do {
|
||||
<h4>Кодогенерация</h4>
|
||||
<p>Как мы убедились, список задач, стоящих перед разработчиком SDK (если, конечно, его целью является качественный продукт) — очень и очень значительный. Учитывая, что под каждую целевую платформу необходим отдельный SDK, неудивительно, что многие вендоры API стремятся полностью или частично заменить ручной труд машинным.</p>
|
||||
<p>Одно из основных направлений такой автоматизации — кодогенерация, то есть разработка технологии, которая позволяет по спецификации API сгенерировать готовый код SDK на целевом языке программирования для целевой платформы. Многие современные стандарты обмена данными (в частности, gRPC) поставляются в комплекте с генераторами готовых клиентов на различных языках; к другим технологиям (в частности, OpenAPI/Swagger) такие генераторы пишутся энтузиастами.</p>
|
||||
<p>Генерация кода позволяет решить типовые проблемы: стиль кодирования, обработка исключений, (де)сериализация сложных типов — словом все те задачи, которые зависят не от особенностей высокоуровневой бизнес-логики, а от конвенций конкретной платформы. Относительно недорого разработчик API может дополнить такой автоматизированный «перевод» правильными настройками используемых системных средств: обеспечить автоматические перезапросы для идемпотентных эндпойнтов (с реализацией какой-то политики), кэширование результатов, сохранение данных (например, токенов авторизации) в системном хранилище и т.д. Такой сгенерированный SDK часто называют термином «клиент к API».</p>
|
||||
<p>Удобство использования и функциональные возможности кодогенерации столь привлекательны, что многие вендоры API только ей и ограничиваются, предоставляя свои SDK в виде сгенерированных клиентов.</p>
|
||||
<p>Генерация кода позволяет решить типовые проблемы: стиль кодирования, обработка исключений, (де)сериализация сложных типов — словом все те задачи, которые зависят не от особенностей высокоуровневой бизнес-логики, а от конвенций конкретной платформы. Относительно недорого разработчик SDK может дополнить такой автоматизированный «перевод» удобными хелпера: обеспечить автоматические перезапросы для идемпотентных эндпойнтов (с реализацией какой-то политики управления интервалами повторных вызовов), кэширование результатов, сохранение данных (например, токенов авторизации) в системном хранилище и т.д.</p>
|
||||
<p>Такой сгенерированный SDK часто называют термином «клиент к API». Удобство использования и функциональные возможности кодогенерации столь привлекательны, что многие вендоры API только ей и ограничиваются, предоставляя свои SDK в виде сгенерированных клиентов.</p>
|
||||
<p>Как мы, однако, видим из написанного выше, проблемы более высокого порядка — получение серверных событий, обработка ошибок в бизнес-логике и т.п. — никак не может быть покрыта кодогенерацией, во всяком случае — стандартным модулем без его доработки применительно к конкретному API. В случае нетривиальных API со сложным основным циклом работы очень желательно, чтобы SDK решал также и высокоуровневые проблемы, иначе вы просто получите множество разработанных поверх API приложений, раз за разом повторяющие одни и те же «детские ошибки». Тем не менее, это не повод отказываться от кодогенерации полностью — её можно использовать как базис, на котором будет разработан высокоуровневый SDK.</p><div class="page-break"></div><h3><a href="#chapter-43" class="anchor" id="chapter-43">Глава 43. Кодогенерация</a></h3><div class="page-break"></div><h3><a href="#chapter-44" class="anchor" id="chapter-44">Глава 44. UI-компоненты</a></h3><div class="page-break"></div><h3><a href="#chapter-45" class="anchor" id="chapter-45">Глава 45. Декомпозиция UI-компонентов. MV*-подходы</a></h3><div class="page-break"></div><h3><a href="#chapter-46" class="anchor" id="chapter-46">Глава 46. MV*-фреймворки</a></h3><div class="page-break"></div><h3><a href="#chapter-47" class="anchor" id="chapter-47">Глава 47. Backend-Driven UI</a></h3><div class="page-break"></div><h3><a href="#chapter-48" class="anchor" id="chapter-48">Глава 48. Разделяемые ресурсы и асинхронные блокировки</a></h3><div class="page-break"></div><h3><a href="#chapter-49" class="anchor" id="chapter-49">Глава 49. Вычисляемые свойства</a></h3><div class="page-break"></div><h3><a href="#chapter-50" class="anchor" id="chapter-50">Глава 50. В заключение</a></h3><div class="page-break"></div><h2><a href="#section-7" class="anchor" id="section-7">Раздел VI. API как продукт</a></h2><h3><a href="#api-product" class="anchor" id="api-product">Глава 51. Продукт API</a><a href="#chapter-51" class="secondary-anchor" id="chapter-51"> </a></h3>
|
||||
<p>Когда мы говорим об API как о продукте, необходимо чётко зафиксировать два важных тезиса.</p>
|
||||
<ol>
|
||||
@ -5834,8 +5834,8 @@ do {
|
||||
<p>В силу этих особенностей аудитории (в первую очередь — малой роли инфлюэнсеров и критического отношения к рекламным заявлениям) доносить информацию до разработчиков приходится через специфические каналы:</p>
|
||||
<ul>
|
||||
<li>коллективные блоги (такие, например, как субреддит “r/programming” или dev.to);</li>
|
||||
<li>сайты вопросов и ответов (StackOverflow, Experts Exchange);</li>
|
||||
<li>обучающие сервисы (CodeAcademy, Udemy и другие);</li>
|
||||
<li>сайты вопросов и ответов (Stack Overflow, Experts Exchange);</li>
|
||||
<li>обучающие сервисы (Codecademy, Udemy и другие);</li>
|
||||
<li>технические конференции и вебинары.</li>
|
||||
</ul>
|
||||
<p>Во всех этих каналах прямая реклама вашего сервиса затруднена или невозможна вовсе. (Точнее, конечно, вы можете купить баннерную рекламу, но мы выразим очень большие сомнения в том, что это поможет вам выстроить отношения с разработчиками.) Вам необходимо генерировать какой-то ценный и/или интересный контент для улучшения знания о вашем API, и эта работа тоже ложится на ваших разработчиков: писать тексты, отвечать на вопросы, записывать обучающие семинары, выступать с докладами.</p>
|
||||
|
||||
BIN
docs/API.ru.pdf
BIN
docs/API.ru.pdf
Binary file not shown.
@ -1,32 +1,32 @@
|
||||
### [Developing a Product Vision][api-product-vision]
|
||||
|
||||
The above-mentioned fragmentation of the API target audience, i.e., the “developers — business — end users” triad, makes API product management quite a non-trivial problem. Yes, the basics are the same: find your audience's needs and satisfy them; the problem is that your product has several different audiences, and their interests sometimes diverge. The end users' request for an affordable cup of coffee does not automatically imply business demand for a coffee machine API.
|
||||
The above-mentioned fragmentation of the API target audience, i.e., the “developers — business — end users” triad, makes API product management quite a non-trivial problem. Yes, the basics are the same: find your audience's needs and satisfy them. The problem is that your product has several different audiences, and their interests sometimes diverge. The end users' request for an affordable cup of coffee does not automatically imply business demand for a coffee machine API.
|
||||
|
||||
Generally speaking, the API product vision must include the same three elements:
|
||||
* Grasping how *end users* would like to have their problems solved
|
||||
* Projecting how *businesses* would solve those problems if appropriate tools existed
|
||||
* Understanding what technical solutions for *developers* might exist to help them implement the functionality businesses would ask for, and where are the boundaries of their applicability.
|
||||
* Understanding what technical solutions for *developers* might exist to help them implement the functionality businesses would ask for, and where the boundaries of their applicability lie.
|
||||
|
||||
In different markets and different situations, the “weight” of each element differs. If you're creating an API-first product for developers with no UI components, you might skip the end users' problems analysis; and, by contrast, if you're providing an API to extremely valuable functionality and you're holding a close-to-monopolistic position on the market, you might actually never care about how developers love your software architecture or how convenient your interfaces are for them — as they simply have no other choice.
|
||||
In different markets and different situations, the “weight” of each element differs. If you're creating an API-first product for developers with no UI components, you might skip the end users' problem analysis. On the other hand, if you're providing an API with extremely valuable functionality and you hold a close-to-monopolistic position in the market, you might actually not care about how developers love your software architecture or the convenience of your interfaces for them, as they simply have no other choice.
|
||||
|
||||
Still, in the majority of cases, we have to deal with two-step heuristics based on either technical capabilities or business demands:
|
||||
* You might first form the vision of how you might help business owners given the technical capabilities you have (heuristics step one). Then, the general vision of how your API will be used to satisfy end users' needs (heuristics step two), or
|
||||
* Given your understanding of business owners' problems, you might make one heuristic “step right” to outline future functionality for end users and one “step left” to evaluate possible technical solutions.
|
||||
* You might first form the vision of how you can help business owners given the technical capabilities you have (heuristics step one) then develop a general vision of how your API will be used to satisfy end users' needs (heuristics step two), or
|
||||
* Given your understanding of business owners' problems, you can take one heuristic “step right” to outline future functionality for end users and one “step left” to evaluate possible technical solutions.
|
||||
|
||||
As both approaches are still heuristic, the API product vision is inevitably fuzzy, and it's rather normal: if you could have got a full and clear understanding of what end-user products might be developed on top of your API, you might have developed them on your own behalf, skipping intermediary agents. It is also important to keep in mind that many APIs pass the “terraforming” stage (see the previous chapter) thus preparing the ground for new markets and new types of services — so your idealistic vision of a nearby future where delivering freshly brewed coffee by drones will be a norm of life is to be refined and clarified while new companies providing new kinds of services are coming to the market. (Which in its turn will make an impact on the monetization model: detailing the countenance of the forthcoming will make your abstract KPIs and theoretical benefits of having an API more and more concrete.)
|
||||
Since both approaches are still heuristic, the API product vision is inevitably fuzzy, and that's quite normal. If you had a full and clear understanding of what end-user products could be developed on top of your API, you might have developed them yourself, bypassing intermediary agents. It is also important to keep in mind that many APIs go through the “terraforming” stage (see the previous chapter), preparing the ground for new markets and new types of services. Therefore, your idealistic vision of a nearby future where delivering freshly brewed coffee by drones becomes the norm of life is to be refined and clarified as new companies providing new kinds of services enter the market. (This, in turn, will impact monetization models as detailing the countenance of the forthcoming will make your abstract KPIs and theoretical benefits of having an API more and more concrete.)
|
||||
|
||||
The same fuzziness should be kept in mind while making interviews and getting feedback. Software engineers will mainly report the problems they've got with the technical integrations, and rarely speak of business-related issues; meanwhile, business owners care little about the inconvenience of writing code. Both will have some knowledge regarding the end users' problems, but it's usually limited to the market segment the partner operates on.
|
||||
The same fuzziness should be kept in mind when conducting interviews and gathering feedback. Software engineers will mainly report problems they encountered during technical integrations and rarely discuss business-related issues. Meanwhile, business owners care little about the inconvenience of writing code. Both groups will have some knowledge regarding end users' problems, but it's usually limited to the market segment in which the partner operates.
|
||||
|
||||
If you do have an access to end users' actions monitoring (see “[The API Key Performance Indicators](#api-product-kpi)” chapter), then you might try to analyze the typical user behavior through these logs and understand how users interact with the partners' applications. But you will need to make this analysis on a per-application basis and try to clusterize the most common scenarios.
|
||||
If you do have access to end users' action monitoring (see “[The API Key Performance Indicators](#api-product-kpi)” chapter), you can try to analyze typical user behavior through these logs and understand how users interact with the partners' applications. However, you will need to conduct this analysis on a per-application basis and attempt to clusterize the most common scenarios.
|
||||
|
||||
#### Checking Product Hypotheses
|
||||
|
||||
Apart from the general complexity of formulating the product vision, there are also tactical issues with checking product hypotheses. “The Holy Grail” of product management — that is, creating a cheap (in terms of resource spent) minimal viable product (MVP) — is normally unavailable for an API product manager. The thing is that you can't easily *test* the solution even if you managed to develop an API MVP: to do so, partners are to *develop some code*, i.e., invest their money; and if the outcome of the experiment is negative (meaning that the further development looks unpromising), this money will be wasted. Of course, partners will be a little bit skeptical towards such proposals. Thus a “cheap” MVP should include either the compensation for partners' expenses or the budget to develop a reference implementation (i.e., a complementary application that is created to support the API MVP).
|
||||
In addition to the general complexity of formulating the product vision, there are also tactical issues with checking product hypotheses. “The Holy Grail” of product management — creating a cheap (in terms of resource expenditure) minimal viable product (MVP) — is typically unavailable for an API product manager. The reason is that you can't easily *test* the solution even if you manage to develop an API MVP. To do so, partners would need to *develop an application*, i.e., invest their money. If the outcome of the experiment is negative, meaning that further development appears unpromising, this money will be wasted. Of course, partners will be a little bit skeptical towards such proposals. Therefore, a “cheap” MVP should include either compensation for partners' expenses or a budget to develop a reference implementation (i.e., a complementary application specifically developed to support the API MVP).
|
||||
|
||||
You might partially solve the problem by making some third-party company release the MVP (for example, in a form of an open-source module published in some developer's personal repository) but then you will struggle with hypothesis validation issues as such modules might easily go unnoticed.
|
||||
You can partially address the problem by having a third-party company release the MVP, for example, in the form of an open-source module published in a developer's personal repository. However, you will struggle with hypothesis validation issues as such modules might easily go unnoticed.
|
||||
|
||||
Another option for checking conjectures is recruiting some other developers within the API provider company to try the API in their services. Internal customers are usually much more loyal towards spending some effort to check a hypothesis, and it's much easier to negotiate MVP curtailing or freezing with them. The problem is that you can check only those ideas that are relevant to the company's internal needs.
|
||||
Another option for checking conjectures is recruiting other developers within the API provider company to try the API in their services. Internal customers are usually much more loyal towards spending some effort to check a hypothesis, and it's much easier to negotiate MVP curtailing or freezing with them. The problem is that you can only validate those ideas that are relevant to the company's internal needs.
|
||||
|
||||
Also, applying the “eat your own dog food” concept to APIs means that the API product team should have their own test applications (so-called “pet projects”) on top of the API. Given the complexity of developing such applications, it makes sense to encourage having them, e.g., by giving free API quotas to team members and providing sufficient free computational resources.
|
||||
Also, applying the “eat your own dog food” concept to APIs means that the API product team should have their own test applications (so-called “pet projects”) on top of the API. Given the complexity of developing such applications, it makes sense to encourage having them, for example, by giving free API quotas to team members and providing sufficient free computational resources.
|
||||
|
||||
Such pet projects are also valuable because of the unique experience they allow to gain: everyone might try a new role. Developers will learn product managers' typical problems: it's not enough to write fine code, you also need to know your customer, understand their demands, formulate an attractive concept, and communicate it. In their turn, product managers will get some understanding of how exactly easy or hard it is to render their product vision into life, and what problems the implementation will bring. Finally, both will benefit from taking a fresh look at the API documentation and putting themselves in the shoes of a developer who heard about the API product for the first time and is now struggling with grasping the basics.
|
||||
Such pet projects are also valuable because of the unique experience they allow to gain: everyone might try a new role. Developers will learn about product managers' typical problems: it's not enough to write good code, you also need to know your customer, understand their demands, formulate an attractive concept, and effectively communicate it. On the other hand, product managers will gain understanding of how exactly easy or hard it is to bring their product vision to life and what challenges they may face. Finally, both groups will benefit from taking a fresh look at the API documentation and putting themselves in the shoes of a developer who is hearing about the API product for the first time and struggling to grasp the basics.
|
||||
@ -1,54 +1,54 @@
|
||||
### [Communicating with Developers][api-product-devrel]
|
||||
|
||||
As we have described in the previous chapters, managing an API product requires building relations with both business partners and developers. (Ideally, with end users as well; though this option is seldom available to API providers.)
|
||||
As we have described in the previous chapters, managing an API product requires building relationships with both business partners and developers. (Ideally, with end users as well, although this option is seldom available to API providers.)
|
||||
|
||||
Let's start with developers. The specifics of software engineers as an audience are the following:
|
||||
* Developers are highly-educated individuals with practical thinking; as a rule, they choose technical products with extreme rationality (unless you're giving them cool backpacks with fancy prints for free).
|
||||
* This doesn't prevent them from having a certain aptitude towards, let's say, specific programming languages or frameworks; however, *affecting* those aptitudes is extremely hard and is normally not in the API vendor's power.
|
||||
* In particular, developers are quite skeptical towards promotional materials and overstatements and are ready to actually check whether your claims are true.
|
||||
* It is very hard to communicate to them via regular marketing channels; they get information from highly specialized communities, and they stick to opinions proved by concrete numbers and examples (ideally, code samples).
|
||||
* The “influencers” words are not very valuable to them, as no opinions are trusted if unsubstantiated.
|
||||
* The Open Source and free software ideas are widespread among developers If you try to make money out of things that must be free and/or open from their point of view (for example, by proclaiming interfaces an intellectual property), you will face resistance (and views on this “musts”… differ).
|
||||
Let's start with developers. The specifics of software engineers as an audience are as follows:
|
||||
* Developers are highly educated individuals with practical thinking. As a rule, they choose technical products with extreme rationality (unless you're giving them cool backpacks with fancy prints for free).
|
||||
* This doesn't prevent them from having a certain aptitude towards, let's say, specific programming languages or frameworks; however, *influencing* those aptitudes is extremely hard and is normally not within the API vendor's power.
|
||||
* Developers are quite skeptical towards promotional materials and overstatements. They are ready to actually check whether your claims are true.
|
||||
* It is very hard to communicate with developers via regular marketing channels. They get information from highly specialized communities and they stick to opinions proved by concrete numbers and examples (ideally, code samples).
|
||||
* The words of “influencers” are not very valuable to them, as no opinions are trusted if unsubstantiated.
|
||||
* The ideas of open source and free software are widespread among developers If you try to make money out of things that they believe should be free and/or open (for example, by proclaiming interfaces as intellectual property), you will face resistance (and views on these “shoulds” differ).
|
||||
|
||||
Because of the above-mentioned specifics (first of all, the relative insignificance of influencers and the critical attitude towards promotions), you will have to communicate to developers via very specific media:
|
||||
Because of the aforementioned specifics (especially the relative insignificance of influencers and the critical attitude towards promotions), you will have to communicate to developers via very specific media:
|
||||
* Collective blogs (like the “r/programming” subreddit or dev.to)
|
||||
* Q&A sites (StackOverflow, Experts Exchange)
|
||||
* Educational services (CodeAcademy, Udemy)
|
||||
* Q&A sites (Stack Overflow, Experts Exchange)
|
||||
* Educational services (Codecademy, Udemy)
|
||||
* Technical conferences and webinars.
|
||||
|
||||
In all these channels, the direct advertising of your API is either problematic or impossible. (Well, strictly speaking, you may buy the banner on one of the sites advertising the advantages of your API, but we hardly doubt it will improve your relations with developers.) You need to generate some valuable and/or interesting content for them, which will improve the knowledge of your API. And this is the job for your developers: writing articles, answering questions, recording webinars, and giving pitches.
|
||||
In all these channels, direct advertising of your API is either problematic or impossible. (Well, strictly speaking, you may buy a banner on one of the sites advertising the advantages of your API, but we highly doubt it will improve your relations with developers.) You need to generate valuable and/or interesting content for them, which will improve their knowledge of your API. And this is the job for your developers: writing articles, answering questions, recording webinars, and giving pitches.
|
||||
|
||||
Developers do like sharing the experience, and will probably be eager to do it — during their work hours. A proper conference talk, let alone an educational course, requires a lot of preparation time. Out of this book's author's experience, two things are crucial for tech-PR:
|
||||
Developers enjoy sharing their experiences and will probably be eager to do so — during their work hours. A proper conference talk, let alone an educational course, requires a lot of preparation time. From this book's author's experience, two things are crucial for tech PR:
|
||||
* Incentives, even nominal ones — the job of promoting a product should be rewarded
|
||||
* Methodicalness and quality standards — you might actually do the content review just like you do the code review.
|
||||
* Methodicalness and quality standards — you might actually do content review just like you do code review.
|
||||
|
||||
Nothing could make the worse counter-advertising for your product than a poorly prepared pitch (as we said, the mistakes will be inevitably found and pointed to) or a badly camouflaged commercial in a form of a pitch (the reason is actually the same). Texts are to be worked upon: pay attention to the structure, logic, and tempo of the narration. Even a technical story must be finely constructed; after it's ended, the listeners must have a clear understanding of what idea you wanted to communicate (and it'd rather be somehow coupled with your API's fitness for their needs).
|
||||
Nothing could be worse counter-advertising for your product than a poorly prepared pitch (as we said, mistakes will inevitably be found and pointed out) or a badly camouflaged commercial in the form of a pitch (the reason is actually the same). Texts need to be worked upon: pay attention to the structure, logic, and tempo of the narration. Even a technical story must be finely constructed; after it's ended, the listeners must have a clear understanding of the idea you wanted to communicate (and it should rather be linked with your API's fitness for their needs).
|
||||
|
||||
A word on “evangelists” (those are people who have some credibility in the IT community and work on promoting a technology or a tech company, being a company's contractor or even a staff member, effectively carrying out all those above-mentioned activities like blog-posting, course-preparing, conference-speaking, etc.) Having an evangelist makes the API development team exempt from the necessity of performing the tech-PR. However, we would rather advise having this expertise inside the team, as direct interaction with developers helps with forming the product vision. (That doesn't mean the evangelists are not needed at all - you might well combine these two strategies.)
|
||||
A word on “evangelists” (those are people who have credibility in the IT community and work on promoting a technology or a tech company, either as a company's contractor or even a staff member, effectively carrying out all those aforementioned activities, such as blog posting, course preparing, conference speaking, etc.) Having an evangelist makes the API development team exempt from the necessity of performing tech PR. However, we would rather advise having this expertise inside the team, as direct interaction with developers helps in forming the product vision. (That doesn't mean evangelists are not needed at all - you might well combine these two strategies.)
|
||||
|
||||
#### Open Source
|
||||
|
||||
The important question which sooner or later will stand in any API vendor's way is making the source code open. This decision has both advantages and disadvantages:
|
||||
The important question that will sooner or later arise for any API vendor is whether to make the source code open. This decision has both advantages and disadvantages:
|
||||
* You will improve the knowledge of the brand, and some respect will be paid to you by the IT community.
|
||||
* That's given your code is finely written and commented.
|
||||
* You will get some additional feedback — ideally, pull requests from third-party developers
|
||||
* And you will also get a number of inquiries and comments ranging from useless to obviously provocative ones, to which you will have to respond politely.
|
||||
* Given that your code is finely written and commented.
|
||||
* You will receive some additional feedback, ideally in the form of pull requests from third-party developers.
|
||||
* You will also receive a number of inquiries and comments ranging from useless to obviously provocative ones, to which you will have to respond politely.
|
||||
* Donating code to open source makes developers trust the company more, and affects their readiness to rely on the platform.
|
||||
* But it also increases risks, both from the information security point of view and from the product one, as a dissatisfied community might fork your repo and create a competing product.
|
||||
* However, it also increases risks, both from an information security point of view and in terms of the product, as a dissatisfied community might fork your repository and create a competing product.
|
||||
|
||||
Finally, just the preparations to make the code open might be very expensive: you need to clean the code, switch to open building and testing tools, and remove all references to proprietary resources. This decision is to be made very cautiously, after having all pros and cons elaborated over. We might add that many companies try to reduce the risks by splitting the API code into two parts, the open one and the proprietary one, and also by selecting a license that disallows harming the company's interests by using the open-sourced code (for example, by prohibiting selling hosted solutions or by requiring the derivative works to be open-sourced as well).
|
||||
Finally, just the preparations to make the code open might be very expensive. You need to clean the code, switch to open building and testing tools, and remove all references to proprietary resources. This decision is to be made very cautiously after considering all pros and cons. We might add that many companies try to reduce the risks by splitting the API code into two parts: the open one and the proprietary one. Additionally, the risks could be mitigated by selecting a license that disallows harming the company's interests by using the open-sourced code (for example, by prohibiting selling hosted solutions or by requiring the derivative works to be open-sourced as well).
|
||||
|
||||
#### The Audience Fragmentation
|
||||
|
||||
There is one very important addition to the discourse: as informational technologies are universally in great demand, a significant percentage of your customers will not be professional software engineers. A huge number of people are somewhere on the track of mastering the occupation: someone is trying to write code in addition to the basic duties, another one is being retrained now, and the third one is studying the basics of computer science on their own. Many of those non-professional developers make a direct impact on the process of selecting an API vendor — for example, small business owners who additionally seek to automate some routine tasks programmatically.
|
||||
There is one very important addition to the discourse: as information technologies are universally in great demand, a significant percentage of your customers will not be professional software engineers. A huge number of people are somewhere on the path to mastering the occupation. Some are trying to write code in addition to the basic duties, others are undergoing retraining, and some are studying the basics of computer science on their own. Many of these non-professional developers have a direct impact on the process of selecting an API vendor, such as small business owners who seek to automate routine tasks programmatically.
|
||||
|
||||
It will be more correct if we say that you're actually working for two main types of audiences:
|
||||
* Beginners and amateurs, for whom each of those integration tasks would be completely new and unexplored territory
|
||||
It would be more accurate to say that API providers are actually working for two main types of audiences:
|
||||
* Beginners and amateurs, for whom each integration task would be completely new and unexplored territory
|
||||
* Professional developers who possess vast experience in integrating different third-party systems.
|
||||
|
||||
This fact greatly affects everything we had discussed previously (except for, maybe, open-sourcing, as amateur developers pay little attention to it):
|
||||
* Your pitches, webinars, lectures, etc., must somehow fit both professional and semi-professional audiences.
|
||||
* A huge share of customers' inquiries to your customer support service will be generated by the first category of developers: it's much harder for amateurs or beginners to find answers to their questions by themselves, and they will address them to you.
|
||||
This fact greatly affects everything we discussed previously (except for, perhaps, open-sourcing, as amateur developers pay little attention to it):
|
||||
* Your pitches, webinars, lectures, etc., must somehow cater to both professional and semi-professional audiences.
|
||||
* A significant share of inquiries to your customer support service will be generated by the first category of developers. It is much harder for amateurs or beginners to find answers to their questions by themselves, and they will reach out to you for assistance.
|
||||
* At the same time, the second category is much more sensitive to the quality of both the product and customer support, and fulfilling their requests might be non-trivial.
|
||||
|
||||
Finally, it's almost impossible in a course of a single product to create an API that will fit well both amateur and professional developers: the former need the maximum simplicity of implementing basic use cases, while the latter seek the ability to adapt the API to match technological stack and development paradigms, and the problems they solve usually require deep customization. We will discuss the matter in “[The API Services Range](#api-product-range)” chapter.
|
||||
Finally, it is almost impossible to create an API that will suit both amateur and professional developers well within a single product. The former need maximum simplicity in implementing basic use cases, while the latter seek the ability to adapt the API to match their technological stack and development paradigms and the problems they solve usually require deep customization. We will discuss this matter in the “[API Services Range](#api-product-range)” chapter.
|
||||
|
||||
@ -211,8 +211,8 @@
|
||||
|
||||
Одно из основных направлений такой автоматизации — кодогенерация, то есть разработка технологии, которая позволяет по спецификации API сгенерировать готовый код SDK на целевом языке программирования для целевой платформы. Многие современные стандарты обмена данными (в частности, gRPC) поставляются в комплекте с генераторами готовых клиентов на различных языках; к другим технологиям (в частности, OpenAPI/Swagger) такие генераторы пишутся энтузиастами.
|
||||
|
||||
Генерация кода позволяет решить типовые проблемы: стиль кодирования, обработка исключений, (де)сериализация сложных типов — словом все те задачи, которые зависят не от особенностей высокоуровневой бизнес-логики, а от конвенций конкретной платформы. Относительно недорого разработчик API может дополнить такой автоматизированный «перевод» правильными настройками используемых системных средств: обеспечить автоматические перезапросы для идемпотентных эндпойнтов (с реализацией какой-то политики), кэширование результатов, сохранение данных (например, токенов авторизации) в системном хранилище и т.д. Такой сгенерированный SDK часто называют термином «клиент к API».
|
||||
Генерация кода позволяет решить типовые проблемы: стиль кодирования, обработка исключений, (де)сериализация сложных типов — словом все те задачи, которые зависят не от особенностей высокоуровневой бизнес-логики, а от конвенций конкретной платформы. Относительно недорого разработчик SDK может дополнить такой автоматизированный «перевод» удобными хелпера: обеспечить автоматические перезапросы для идемпотентных эндпойнтов (с реализацией какой-то политики управления интервалами повторных вызовов), кэширование результатов, сохранение данных (например, токенов авторизации) в системном хранилище и т.д.
|
||||
|
||||
Удобство использования и функциональные возможности кодогенерации столь привлекательны, что многие вендоры API только ей и ограничиваются, предоставляя свои SDK в виде сгенерированных клиентов.
|
||||
Такой сгенерированный SDK часто называют термином «клиент к API». Удобство использования и функциональные возможности кодогенерации столь привлекательны, что многие вендоры API только ей и ограничиваются, предоставляя свои SDK в виде сгенерированных клиентов.
|
||||
|
||||
Как мы, однако, видим из написанного выше, проблемы более высокого порядка — получение серверных событий, обработка ошибок в бизнес-логике и т.п. — никак не может быть покрыта кодогенерацией, во всяком случае — стандартным модулем без его доработки применительно к конкретному API. В случае нетривиальных API со сложным основным циклом работы очень желательно, чтобы SDK решал также и высокоуровневые проблемы, иначе вы просто получите множество разработанных поверх API приложений, раз за разом повторяющие одни и те же «детские ошибки». Тем не менее, это не повод отказываться от кодогенерации полностью — её можно использовать как базис, на котором будет разработан высокоуровневый SDK.
|
||||
|
||||
@ -18,8 +18,8 @@
|
||||
|
||||
В силу этих особенностей аудитории (в первую очередь — малой роли инфлюэнсеров и критического отношения к рекламным заявлениям) доносить информацию до разработчиков приходится через специфические каналы:
|
||||
* коллективные блоги (такие, например, как субреддит “r/programming” или dev.to);
|
||||
* сайты вопросов и ответов (StackOverflow, Experts Exchange);
|
||||
* обучающие сервисы (CodeAcademy, Udemy и другие);
|
||||
* сайты вопросов и ответов (Stack Overflow, Experts Exchange);
|
||||
* обучающие сервисы (Codecademy, Udemy и другие);
|
||||
* технические конференции и вебинары.
|
||||
|
||||
Во всех этих каналах прямая реклама вашего сервиса затруднена или невозможна вовсе. (Точнее, конечно, вы можете купить баннерную рекламу, но мы выразим очень большие сомнения в том, что это поможет вам выстроить отношения с разработчиками.) Вам необходимо генерировать какой-то ценный и/или интересный контент для улучшения знания о вашем API, и эта работа тоже ложится на ваших разработчиков: писать тексты, отвечать на вопросы, записывать обучающие семинары, выступать с докладами.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user