Mapping your API

- [Instructor] So far, this entire course has been from the perspective of having an existing API with good documentation, or maybe even adding tests as we're building the API itself. Those two scenarios are the best by far. In fact, if you have one of those, you can skip the rest of this video and go onto the next one, and go directly to prioritizing your endpoints. But for the rest of us, keep watching. If you have an existing, well-documented API, or are actively building your API now, that's awesome. But the third scenario, the third scenario comes up a little more often and is way more painful. In this case, we have an existing, poorly documented API, which is critical to our systems, app, or even company as a whole. Frankly, this is the worst of all worlds. The API is critical to our business and we need it to be online and functional, but we still have to maintain it. Even worse, we probably have to update and extend this API over time. Unfortunately, after many years of building APIs, I found this is the most common situation by far. So how do we test and verify this API? It turns out, one step at a time. When we start mapping our API, the goal is to understand what endpoints our API has and which are actually used. If we have an API gateway or some sort of proxy, we should be able to see the individual URLs and potentially even see and review the parameters and payloads. If we're lucky, the API uses hypermedia, and all the URLs of the API are in the payload itself, but unfortunately, that's not very common. More likely, we're going to have to get more creative. My favorite approach is to review the source code of our applications and see what URLs are embedded in them. For apps that use static fixed strings, we should be able to find most of them. For apps that construct URLs, we may have to search for the base URL or host name, and expand our search from there. We still need to understand the request and responses, but then, we still need to understand the request and responses. We can add a local proxy, like Charles, Squid, or ngrok, and update the application to use that URL instead of our API directly. The proxy can then capture all the requests and responses and log them. Now we can review the endpoints and see which ones we use, and what data they actually take in return. Alternatively, there is some magic you can work with DNS, IP address routing, and proxies that's well beyond the scope of this course. But getting into the flow of the API requests gives you a huge amount of power and insight. Whichever approach you choose, once you're collecting real live information, make sure to collect production usage and use cases that are as close to the real world as possible. Specifically, you need the URLs your apps use and the parameters and payloads that move back and forth. You need to figure out what API endpoints your app actually cares about. And there's a subtle final point in there. Odds are our proxies, logging, and whatever approach we use will not get every endpoint possible from the API. Instead, it will capture the URLs most commonly used, or the ones used by the most important capabilities, and completely miss others. That's fine. Frankly, I don't believe in writing tests for code that never gets used. Now that we have our endpoints, we can move on to our next step, documentation.