TechnicaL FOUNDATIONS for Product managers
Is finding and reading API docs a PM job? Yes, it is part of a product research. Let's figure out how to do it effectively using an example of a real DeepL API.
A typical product situation…
If you are unsure what API is and why PMs should care, I suggest starting with this post.
Today, you are a PM in a big online shop with an idea for a cool new feature for Customer Support. You will auto-correct text written by support agents to ensure your company's communications sound concise and professional. All spelling mistakes, typos, and so on will be fixed in one click.
Before bothering your development team with this great idea, you’d like to quickly check which functionality is already available on the wild Internet so that your JIRA ticket to them is clear and concrete: get this data, send it to this API, get back the answer from the API, use it in product to do X (we’ll see later what), run an experiment, profit.
Today, you are a PM in a big online shop with an idea for a cool new feature for Customer Support. You will auto-correct text written by support agents to ensure your company's communications sound concise and professional. All spelling mistakes, typos, and so on will be fixed in one click.
Before bothering your development team with this great idea, you’d like to quickly check which functionality is already available on the wild Internet so that your JIRA ticket to them is clear and concrete: get this data, send it to this API, get back the answer from the API, use it in product to do X (we’ll see later what), run an experiment, profit.
The steps
Step 1. Start by searching for the functionality you are looking for (internally in the company or on Google). In our case, go with “translate API,” and let’s choose DeepL. Here is a link to their docs.
Step 2. Read the description of the API endpoint that best suits the requirements. DeepL has a few (/translate text, translate documents, etc), but we need the “Improve text” one. It seems that example does exactly what we are looking for - it fixes a broken text:
Step 3. Understand the input parameters we must send from our product to the DeepL API.
Look at the documentation and try to answer the following question yourself:
Look at the documentation and try to answer the following question yourself:
What is the only required input parameter?
Text_to_improve
Text
Target_lang
As we can find in the “Request” section, there is a single required parameter (text) and a few optional ones (tone, writing_style, target_lang). Interesting! This means that we can fix typos and make our agents' writing a bit more “warm.”
Look at the documentation and try to answer the following question yourself:
Look at the documentation and try to answer the following question yourself:
Which value of the "tone" param will help with that?
— tone=friendly
— tone=compassionate
— tone=compassionate
Looking at the documents, I see that the former should do the trick.
Step 4. Understand the output parameters (what we will receive from the API and use in the product). In this case, API returns the improved text in the parameter… text. Our developers can take it from the API and use it in the product: we probably want to show it one more time to the CS agent to review before sending it to the customer.
Step 5. Understand possible errors (to prepare the product for the fact that the response will not always be successful). In this case, it is pretty simple: if we set the parameters correctly, we will probably get the improved text. If not, the API will return an error, so we’ll have to tell the CS agent, “Sorry, you have to improve the message yourself.”
Step 6. Finally, you need to check if the API has any specifics. For example, is the API asynchronous, or can it return non-obvious results? Or is there a chain of calls: service A calls service B, which calls service C, which finally calls the DeepL API? In this case, you need to do a bit of a deep dive and build a Sequence Diagram. If you want to practice that, check out this hands-on course. API is quite simple in this case, so we do not need anything else.
Step 7. Finally, you are all set to write a dev story for your team: what/why to connect, what parameters to send, what to get back, and how to use it in the product. Good job!
Step 4. Understand the output parameters (what we will receive from the API and use in the product). In this case, API returns the improved text in the parameter… text. Our developers can take it from the API and use it in the product: we probably want to show it one more time to the CS agent to review before sending it to the customer.
Step 5. Understand possible errors (to prepare the product for the fact that the response will not always be successful). In this case, it is pretty simple: if we set the parameters correctly, we will probably get the improved text. If not, the API will return an error, so we’ll have to tell the CS agent, “Sorry, you have to improve the message yourself.”
Step 6. Finally, you need to check if the API has any specifics. For example, is the API asynchronous, or can it return non-obvious results? Or is there a chain of calls: service A calls service B, which calls service C, which finally calls the DeepL API? In this case, you need to do a bit of a deep dive and build a Sequence Diagram. If you want to practice that, check out this hands-on course. API is quite simple in this case, so we do not need anything else.
Step 7. Finally, you are all set to write a dev story for your team: what/why to connect, what parameters to send, what to get back, and how to use it in the product. Good job!
Summary
Just 15 minutes of product research, and you can set a well-defined task for your team (or for Replit/Bolt/etc. AI code generators if you are one of the cool kids playing with a new tech).
Of course, there is more to say and practice on the API topic, and one example won’t make you a guru (but five will get you closer!). If you like to gain the skill in the question/answer manner as we did in the article, there is a self-paced hands-on course where you solve tasks with virtual colleagues.
Many PMs have already enjoyed the course (see reviews) and become more effective in their job, and so will you.
Of course, there is more to say and practice on the API topic, and one example won’t make you a guru (but five will get you closer!). If you like to gain the skill in the question/answer manner as we did in the article, there is a self-paced hands-on course where you solve tasks with virtual colleagues.
Many PMs have already enjoyed the course (see reviews) and become more effective in their job, and so will you.