3 strategies for troubleshooting API issues

Imagine this: you’re creating an app that uses the Stripe API to incorporate payment processing functionality. Since Python is your language of choice, you’re using the Python client library (SDK) to interact with the Stripe API. So far so good — initially everything seems to be going well. But then out of the blue, things go sideways — one of the Stripe API calls your Python app is issuing isn’t having the intended effect. What the heck?!

In an ideal world, your app would function flawlessly from day one and there’d never be a need to investigate issues with your API integration. Unfortunately, that’s rarely the case. In this post, we’ll discuss 3 strategies for troubleshooting API issues in your app.

Strategy #1: Delve into the docs

You might be surprised how many issues can be resolved by simply reading the API docs. What’s the recommended way to do what you’re trying to do? Are there any special caveats or considerations that come into play? And, how does your (problematic) implementation differ from the recommendation(s) provided by the docs? Find the answers to these questions, and you’ll be up and running again in no time.

Strategy #2: Search out code samples

Okay, so you’ve read the API docs and still don’t feel any closer to resolving the issue with your integration. Next stop: code samples! I use the term code samples loosely — depending on the problem you’re trying to solve, the answer may be found in:

A code snippet or code example (in the API docs)
A quick start or tutorial (in the API docs)
Code examples for the SDK you’re using (in the API docs or the GitHub repo for the SDK)
The unit test code of the open-source SDK you’re using (in the GitHub repo for the SDK)
A collection of code samples (in the Dev Center or the GitHub account of product you’re integrating with)
A full-blown sample app (in the Dev Center or the GitHub account of product you’re integrating with)

Sometimes you’ll be able to find a code sample that aligns well with your scenario, but if not, even finding a somewhat related code sample in the language of your choice can often be enough to get you headed in the right direction.

Strategy #3: Step away from the code

If API docs and code samples don’t shed light on your problem, it’s time to step away from the code. I repeat: STEP AWAY FROM THE CODE.

Confirm the structure and contents of a successful request

You could easily lose hours to tinkering with your code, attempting to resolve an API issue. Don’t make this mistake! Instead, use information from the API docs to craft a request in cURL or Postman that has the intended effect. By taking your code out of the equation, you can focus purely on confirming the structure and contents of a successful request.

Identify the structure and contents of the failing request

Next, you need to examine the data that’s being sent & received for the failing request in your app. Be sure to pay attention to all parts of the API request: verb, endpoint, HTTP headers, and body.

If you’ve followed the advice in 6 keys to designing a successful API integration, your app has the ability to log the request and response data that it’s sending and receiving when interacting with the API. Alternatively, you may choose to use a tool like Fiddler to inspect the request and response data as it’s travelling back and forth between your app and the API server.

Either way, the goal is the same: identify the structure and contents of the failing request that your app is issuing.

Compare the failing request to the successful request

Finally, at this point you know:

The structure and contents of a successful API request.

The structure and contents of the failing API request that your app is issuing.

You can now compare the structure and contents of the failing request to that of the successful request, and update your code to correct any discrepancies. Because you’ve identified the exact changes that are required, updating your code should be fairly straightforward.

So there you have it…

…3 strategies for troubleshooting API issues:

Delve into the docs.
Search out code samples.
Step away from the code.

The next time you run into issues with your API integration, give these strategies a try! If you’re still stuck, don’t be discouraged — it’s totally normal to encounter problems that you’re unable to solve on your own. In the next series, we’ll discuss Getting Help — how to effectively enlist help from others when you’re stuck. But first — a quick knowledge check:

Twitter