- Skiplevel Newsletter
- Posts
- [Part 3] PM Best practices for debugging APIs & OAuth 2.0
[Part 3] PM Best practices for debugging APIs & OAuth 2.0
Irene Yu
November 28, 2023
Every month I share a Tech Term You Should Know (TTYSK) and a tech essay to level up your technical chops as a product manager and get the most out of dev teams. Ask me anything and I'll cover it in an upcoming newsletter issue.
This issue's TTYSK is OAuth 2.0 and the essay is Debugging APIs.
OAuth 2.0 is available technology that you should be aware of as a more user-friendly alternative to the typical login flow. Knowing how to Debug APIs will empower you to play an active part in the life of your product during critical times.
In this 3-part “Guide to APIs” series, I’ll walk you through the critical API knowledge you need to know as a PM. We won’t go deep into implementation—just deep enough for you to be dangerous.
[Part 3] PM Best Practices for Debugging APIs
Black Friday Promo: Level up your technical skills and ability to communicate with engineers.
Take advantage of our Black Friday deal before it ends Fri, 11/30 at midnight ET! $100 off program enrollment and an additional year access. Available to new students only.
Become more technical in just 5 weeks, without learning to code. Find out if Skiplevel is the right fit for you team at skiplevel.co/is-skiplevel-right-for-me.
If you're not a subscriber, check out what you missed in past newsletters.
[Part 3] PM Best practices for debugging APIs
Ask me anything & I'll answer it in an upcoming issue.
If you missed Part 2 of this 3 part “Guide to APIs” series, check it out here.
You’re a product manager and you receive a complaint from your customer about errors using your app. What do you do? How do you respond? You might decide to ping an engineer and wait for them to implement a fix. After all, you’re not in the code and there’s only so much you can do.
But this couldn’t be further from the truth. Regardless of the cause, you can play an active part in resolving errors quickly by trying to understand as much about the cause of the error. For example, is it a user error, an issue with an internal API, or a third-party issue? To find out, you’ll need to learn how to debug an API as a core technical skill.
So in this tech essay, I’ll go over useful tools and methodologies for debugging APIs more quickly and reliably.
Tools for Debugging APIs
Before we dive deeper into the steps for debugging an API, let’s go over a couple of popular tools we can use in the process.
Developer Tools
Developer tools, or DevTools for short, are a set of software tools that help developers debug, test, and optimize web apps. Developer Tools are built directly into the browser and developers use them on a regular basis to inspect the frontend code of a web page, view network activity, debug JavaScript, and more.
For example: Google Chrome’s Developer Tools, also known as Chrome DevTools, is a popular web developer tool that’s built directly into the Google Chrome browser. You can check out Chrome’s DevTools yourself by opening up Chrome -> Click “View” -> Hover over “Developer” -> Click “Developer Tools”, or you can use the shortcut “Option + Command + i” (“Option + Control + i” for PC).
There are a number of tabs in DevTools, each serving a specific purpose. For this essay on debugging APIs, we’ll focus on the “Network” tab and the “Console” tab.
In the “Network” tab, you’ll see all the network interactions between your browser and the server-side (backend) through APIs:
Network tab of Chrome’s DevTools
The “Console” tab allows you to interact with web pages and web applications. It is a command-line interface that provides a way to execute JavaScript code, log messages, and debug code:
Console tab of Chrome’s DevTools
Postman API
If you’ve been working in tech for a while, you’ve likely interacted with or at least heard of Postman. Postman API is a popular app that simplifies the process of building, using and testing APIs. It offers a comprehensive set of tools that help accelerate the API lifecycle — from design, testing, and documentation to the mocking and sharing of APIs.
Postman is a great tool for debugging APIs. It provides a simple and intuitive UI where we can make API calls and play around with the inputs (request attributes) to see the effects on the outputs (response). Here’s what it looks like:
Postman API
How to Debug an API
Alright, now that you’re familiar with the tools, let’s jump into how to debug an API.
The first step to debugging any error is getting as much information as possible from the user about what they’re experiencing. Ask them for the exact steps to reproduce the error including text they’re entering into a form. Screenshots are also very helpful.
From there, you can try and reproduce the error yourself to identify if it’s a user error or something else. If it doesn’t appear to be a user error, we want to start looking at API requests happening and debug them.
Debugging an API means identifying and fixing issues with a single API call or sequence of calls. This requires you to understand what the relationship is between the inputs (API request) and outputs (API response) and then locating the root cause of the issue based on those inputs and outputs. This understanding will help reduce the time and effort required for your team to find and fix the issue.
The steps for debugging an API can be broken down into four parts:
Identify the problematic API
Check the status code and response
Examine the API data more closely
Experiment with the API inputs
Step 1: Identify the problematic API
The first step to debugging an API issue is to identify which API(s) are causing the issue. To do this, you want to reproduce the error with developer tools open. For the rest of the essay we’ll use Chrome’s Developer Tools as an example.
After opening up Chrome’s Developer Tools, click on the “Network” tab and filter for Fetch/XHR. This will show you all the API requests that’s being made from the website. If you don’t see any or many API requests, check “Preserve Log”, reload the page, and re-do the steps needed to reproduce the error.
From here, you can check the API status code. Identify the ones that aren’t 200 meaning they were not successful.
Network tab in Chrome’s Developer Tools
Step 2: Check the status code and response
Our first clue for debugging the problematic API(s) is by looking at its status code and then it’s error message. APIs return a HTTP status code that represents whether the request was successful, or something went wrong in which case an error message is returned in the response. No two APIs are exactly the same since status codes and error messages are not automatically assigned. They’re created by the API provider and they decide how much information they want to include or not include.
However, status codes tend to be fairly standard as they follow an established convention. For example, all status codes in the 200s indicate the API functioned perfectly and as intended. Status codes in the 400s indicate a bad request was made by the client and therefore it’s an issue you can potentially solve. Status codes in the 500s indicate there was an issue on the server-side which requires a more involved process for debugging since it’s an issue that needs to be fixed by the API provider.
Here are some common 400 status error codes and what you can do when you encounter one of these errors:
400 Bad Request: Check if you’re missing data required by the API request or if there was a typo.
401 Unauthorized: Check if your authentication credentials are valid. They’re usually included in the headers.
403 Forbidden: Check your permissions and scope to ensure you are authorized to access the resource.
429 Too Many Requests: The API rate limit might have been hit. Wait for some time and try again later.
If you encounter any of these status codes, you’ll likely also find an error message that might give you a little more information about what the issue is and how to possibly fix it.
Step 3: Examine the API data more closely
After examining the status code and the error message, the next step is to dig deeper and examine all parts of the API. You want to check the API endpoint, any endpoint parameters, the headers, and the API request body. You can do this in developer tools.
... (read more below)
💡 Tech Term You Should Know (TTYSK)
"OAuth 2.0"
Whenever you log into a website using your Google or Facebook account, you're using a technology called OAuth.
Logging into Spotify using Facebook with OAuth 2.0 under the hood.
OAuth is a protocol that allows you to grant permission to a third-party application to access your data from another website or application without sharing your login credentials. OAuth does this by providing access tokens and refresh tokens to third-party services instead of exposing your login credentials. Access tokens are used to log in to the authorization server (i.e. Google or Facebook) and refresh tokens are used for getting new access tokens when they expire.
There are 4 different OAuth 2.0 flows developers can implement depending on the requirements:
Authorization Code Flow: For regular web apps executing on a server. Allows the client to retrieve an Access Token and, optionally, a Refresh Token.
Implicit Flow with Form Post: For Single-Page Apps (SPAs). The client can retrieve an Access Token and, optionally, a Refresh Token. The Access Token is passed directly to the web server hosting the client, without going through the user’s web browser and risking exposure.
Resource Owner Password Credentials Grant: Suitable for when the client is absolutely trusted with user credentials. The user is asked to fill in credentials (username/password) and this information is sent to the backend servers and from there to the Authorization Server.
Client Credentials Flow: For machine-to-machine authorization. The client is also the Resource Owner, so no end-user authorization is needed.
You don't need to memorize the exact differences of each of these right now—just being aware of the 4 flows and what they are generally is good enough. You can dig deeper if the use case ever presents itself.
So how does it work? I'll give you a real world example using the Authorization Code Flow. There are 4 main actors in OAuth 2.0:
Resource Owner: You, the user.
Client: Third party app you want to log into using OAuth.
Authorization Server: The server that issues and validates the access and refresh tokens.
Resource Server: The server that shares data with the third-party app.
Imagine you are the resource owner, the client is Spotify, and the server is Facebook. Here's how OAuth 2.0 works under the hood:
Now every time Bob tries to log into Spotify, Spotify will automatically validate the access token it has in its database with Facebook's authorization server so Bob won't need to login each time!
What to know about OAuth 2.0 as a PM:
Having a general understanding of OAuth and what it takes to implement the feature will help you write better requirements from the get-go and have better conversations with engineers.
The complexity and time required to implement OAuth depends on a number of factors including the specific requirements of your application, your developer’s familiarity with OAuth, and the programming language being used.
For example, a guide from Okta suggests that you can integrate OAuth 2.0 in a Java application in less than 5 minutes, though that assumes a high level of familiarity with both Java and OAuth and is a best case scenario.
In general, implementing OAuth involves several steps, including:
1. Setting up the OAuth provider
2. Configuring your application with the provider
3. Writing code to handle the OAuth flow.
This process could take anywhere from a few hours to a few days, depending on the complexity of the application and the developer’s experience. At maximum, implementing OAuth shouldn't take more than a full 2 week sprint.
How do you rate the Skiplevel newsletter?I need your help! Tell me how I can improve this newsletter. |
Missed the mid-month PM & Tech Jobs Newsletter?
Looking for a new job? Our PM & Tech Jobs newsletter is issued monthly with product role job listings from senior to entry-level roles.