One Tool, All APIs: PowerShell As The All-Purpose API Client

Another series where we will be covering all aspects of consuming and interacting with APIs using  PoweShell only (what a shocker =P).

An Application Programming Interface is a way for two or more computer programs to communicate with each other. Basically, it is a type of software interface, which is offering a service to other pieces of software.

First of all, let get on the same page about definitions and types of APIs that are available in the wild. As far as I am aware there are four API types.

1. XML-RPC and SOAP APIs are older legacy types of APIs that use XML (eXtensible Markup Language) for communication. They have pretty strict and rigid structure and lack flexibility. Nowadays, they are still in use in the enterprise environments.
2. RESTful APIs (Representational State Transfer) are designed for network applications and are considered de facto standard. They use HTTP methods (GET, POST, PUT, and DELETE) to interact with resources via URL endpoints. Typically used in web and mobile apps as they are pretty easy to use and are supported by all programming languages.
3. GraphQL APIs (new and shiny) used as a query language and runtime for APIs that enables clients to request exactly the data they need and nothing more. One of the shortcomings of REST that you are bound with fixed set of data returned by each API endpoint. GraphQL is much more flexible as it allows clients to define the structure of the response, resulting into more efficient data retrieval.
4. WebSocket APIs (pretty niche ones) uses protocol that provides full-duplex communication channels over a single TCP connection. Generally used for real-time communication, such as chat applications or live data feeds, where client and server can send data to each other without waiting for a request.

Why API?

Nowadays, modern products and services development is starting with API. Majority of the companies are following API-first development. It is pretty self-explanatory, first developers are creating API endpoints with some functionalities and then build and Application or Service which is utilizing the aforementioned API. This approach provides more flexibility and also opens up the opportunities for ISV (Independent Software Vendors) to create their version of an app, while still consuming the original vendor’s API.

According to 2023 State of the API Report by Postman:

… more respondents embraced a thorough API-first approach to development: 11% ranked themselves as highly API-first. That’s up from 8% in each of the prior two years.

It is an annual survey of developers and API professionals; current one is the fifth one. I highly recommend reading the whole report here and to get you more interested & curious about it here are the summary of key findings:

Now, I hope that I’ve convinced you that API is important and very much needed for business digitalization and integrations, so let’s get to the very topic of the post – API clients.

API Clients

During the API development, developers need to test and interact with API to see the progress and receive immediate feedback and debugging. There are myriad of API clients available in the wild, I would like to highlight few most popular ones.

• CURL – free and open-source command line tool and library for transferring data with URLs. Primarily it was developed (back in 1998) for manual API interaction and testing. Because it is a CLI tool it is also heavily used in scripts and automation. Curl supports 27+ protocols and includes features and functionalities such as FTP uploading, cookies, file transfer resume, proxy tunneling, DNS-over-HTTPS, and more.

• PostMan API Client is part of the PostMan API platform. PostMan itself is an API platform for building and using APIs, which simplifies each step of the API lifecycle and streamlines collaboration. API client from PostMan allows easily explore, debug, and test APIs. It supports complex API requests for HTTP, REST, SOAP, GraphQL, and WebSockets.

• Web browser extensions, provide a user-friendly interface and tools for sending HTTP requests, viewing responses, and inspecting API data. These extensions are very convenient for developers and testers as they allow you work within the web browsers. They support wide range of features for managing authentication, handling request parameters, and organizing API requests into collections for efficient testing and development workflows. The choice of extension depend on your browser preference and specific needs: Google Chrome, Mozilla FireFox, Microsoft Edge.

• Visual Studio Code Extensions. As you know, Visual Studio Code (VS Code) is pretty popular free and open-source code editor & IDE (Integrated Development Environment) that offers a wide range of extensions to enhance its functionality. As developers provide most of the time creating & debugging code, VS Code API Client extensions are the perfect complement for dev workflow to allow them use single pane of glass for coding and interacting/testing the APIs.

• Burp Suite – the class-leading vulnerability scanning, penetration testing, and web app security platform. There are free and enterprise versions available. Burp Suite Community Edition are the best manual tools to start web security testing for free. It supports HTTP(s) / WebSockets proxy and requests history, as well as proprietary tools – Repeater (modify and send an interesting HTTP or WebSocket message over and over), Decoder (transform data using common encoding and decoding formats), Sequencer (analyze the quality of randomness in a sample of tokens), and Comparer (compare any two items of data). It is so much more than just an API client which allows to interact with APIs.

As you can see different API clients have their weaknesses and strength and are leaning towards covering the specific use cases. In our made-up universe we are bound to use PowerShell only, so let’s see what the Founding Fathers provide us Out of the Box.

Out of the Box

Right of the bat, we are presented with 2 primary cmdlets for interacting with Web services – Invoke-WebRequest and Invoke-RestMethod. They are both part of the Microsoft.PowerShell.Utility module and are commonly used for making HTTP requests to web services or websites.

Invoke-WebRequest gets content from a web page by returning a WebResponseObject that contains information about the HTTP response, headers, content and status code. More details can be found here.

Let’s look into simple example of using Invoke-WebRequest. (In the examples we will be using The Star Wars API aka SWAPI).

$r=Invoke-WebRequest -Uri https://swapi.dev/api/people/4

Invoke-RestMethod sends an HTTP or HTTPS request to a RESTful web service, it is designed to simplify working with JSON and XML data returned by APIs. Please refer to the documentation for more details.

Let’s try to interact with the same API endpoint:

 $r=Invoke-RestMethod -Uri https://swapi.dev/api/people/4

As you can see, there is a difference in the amount of information returned (at least) when we are using different cmdlets. Let’s analyze Invoke-WebRequest and Invoke-RestMethod in more details.

WebRequest vs RESTMethod

In conclusion, as you can see Invoke-WebRequest has more general-purpose functionality and is suitable for web scraping, downloading files, interacting with web forms, or handling non-structured data. Whereas Invoke-RestMethod is kind of niche cmdlet, tailored for working with RESTful APIs, as it simplifies data parsing. The main criteria for chosing one over another is format of the data you are handling.

Next: API Authentication with PowerShell.

Icons created by Freepik – Flaticon.

Thanks a lot for reading.