Author: Training Committee

In its recent 54^th general members meeting, the Messaging, Malware, and Mobile Anti-Abuse Working Group (M3AAWG) offered several training sessions, including “Learning to Access a Sample API In Python3." Key takeaways are summarized here.

The Premise and Approach

The premise for this training was that you may routinely see sites offering API ("Application Programmer Interface") access to interesting services, but if you're NOT a professional developer you may assume that there's "no way" you could ever build your own code to consume such an API.

The session took an iterative approach to creating a small demonstration graphical application in Python3 using data made available by the RIPEstat Data API (see ). You don't HAVE to write you own application to use the RIPEstat Data (they have a very nice professionally written application available at that you can use to get at that data), but in our example, we selected that API as (a) a data source relevant to those investigating cyber abuse, and (b) a handy "vendor neutral" API data source that would work for demonstration purposes. Every API will be different, yet sufficiently similar, that the demonstrated API access process SHOULD "generalize."

What's Involved in Accessing An API

The session addressed the choice of Python3 and Tkinter (rather than one of the numerous alternatives), likewise the use of the "requests" library for making https requests. We then went on to outline the steps that pretty much any API-accessing application needs to handle:

1. Putting up a graphical user interface (GUI) to accept query parameters from the user
2. Using those user-supplied parameters to build the RESTful query you want to run
3. Passing the RESTful query to the API server over an HTTPS connection
4. Handling any errors (authentication errors, time outs, etc.)
5. Processing the output (often in JSON) and displaying the formatted results back in the GUI interface

In this particular case, the plan was to:

1. Begin by getting a domain name from the user
2. Resolve that domain name to get the IPv4 address (or addresses) corresponding to that domain name
3. Get selected IP Whois information for those IPv4 IP address(es) using https://stat.ripe.net/docs/02.data-api/whois.html
4. Display the output we've decided we want.

Sample output might look like: 

That's NOT a very sophisticated application -- intentionally so! It was meant to be a simple introduction to building SOME SORT of code of your own that accesses an API, in this case, the RIPEstat API. Think of this as a "Hello, World!" of sample API applications, just retrieving and displaying four bits of information (out of a LARGE number of potentially interesting bits), BUT if you can do it for even four chunks of information, you could do it for a far larger and more sophisticated set of information from that API, too.

You could have imagined and built something COMPLETELY different, there's no single "right" (or "wrong") sample API application -- YOU have the creative power when it comes to choosing what you build from data that's available to you via an API.

The Iterative Phases

Four versions of the code were developed (and shared via Pastebin) iteratively enhancing the application:

• Version "A" of the sample application (just two PowerPoint slides' worth of Python3) was all it took to get a basic graphical user interface up and running.
• The training then interactively introduced the process of using socket.gethostbyname_ex() to resolve the user-supplied domain name, and what might be needed to process the IPs that might be returned, an example of using a service routine to translate what the user knew and could provide to what the API might actually require
• Version "B" of the sample application handled composing the query to be made, making the query, checking the return code for that query, and lashing that query function into the Tkinter interface, including writing the output to a scrollable output area
• Version "C" of the sample application explained how to work with JSON Lines format results, extracting just the selected data items we wanted, whether those items were named JSON elements or key/value pairs from an array (in many ways, this is the most tedious/painful part of the whole process)
• Version "D" of the sample application handled making the application a little "prettier," tweaking fonts, backgrounds, spacings and so forth, adding a "Clear" and "Quit" button, and doing some simple error handling.
• Other more in-depth resources were offered, including books about Python, in-depth/formal Python training (such as the Coursera Python modules), as well as things like the Python subreddit and the Python mailing list

You can find M3AAWG best practices at https://www.m3aawg.org/published-documents