PowerShell Basics – Consuming Web APIs

Over the weekend I decided to do some tinkering with data from my long list of vinyl records.  I’ve been trying to ensure that the more valuable LPs are stored away from the hands of my little cohorts – and popular website discogs.com happens to have both marketplace data, and a free web API.  I have already matched LPs from my collection to releases documented on the Discogs website which can take hours over many years to get the correct matches.  To learn more about Discog’s developer support, check out the Developer section on the site.

I thought this process would make for an interesting beginner’s guide to using PowerShell to interact in a meaningful way with Web APIs.  As an aside, the DIscogs developer pages lack samples in C# or PowerShell, so I thought this might be useful for those who don’t speak Ruby, PHP or Python.

The basics

Why don’t we start out with a basic scenario.  Say I just wanted to look up information about a single release (album), given the release number Discogs uses to identify individual LPs?  I have a copy of the Smashing Pumpkins’ Siamese Dream, which happens to be release 1845456.  To use PowerShell to make an API request, I need a few lines of code, and most of it is to format the result data.

First off, I put the release into a variable (making it clean to maintain).  For basic release info, you don’t need to authenticate, so you can immediately launch a request of the API to return the release information, which is done easily like this:

   1: $releaseNo = 1845456

   2: $release = Invoke-WebRequest -uri https://api.discogs.com/releases/$releaseNo

   3: $json = ConvertFrom-Json $release.Content

Now, to get the marketplace information you need to have an authorization token.  If you create an account on the site, you can request a personal use API token from the developer pages.  You need to copy the personal use token and insert it into the script in order to make authenticated API calls.

To do this in PowerShell, define a variable for HTTP HEADER information, and then make an authenticated request like so:

   1: $h2 = @{}

   2: $h2.Add('Authorization', 'Discogs token=<YOUR_PERSONAL_USE_TOKEN>')

   3:  

   4: $market = Invoke-WebRequest -uri https://api.discogs.com/marketplace/price_suggestions/$releaseNo -Headers $h2

   5: $json2 = ConvertFrom-Json $market.Content

If you planned to make greater use of the API, you’d instead use complete OAuth lifecycle access tokens, which is documented in the Discogs development pages.

Once you have this working, all you need to do is format the returned results into something more concrete, like this:

   1: $details = @{            

   2:             Artist       = $json.artists[0].name

   3:             Album        = $json.title            

   4:             Release      = $releaseNo 

   5:             CurrentDate  = Get-Date 

   6:             'Very Good (VG)'       = $json2.'Very Good (VG)'.value 

   7:             'Very Good Plus (VG+)' = $json2.'Very Good Plus (VG+)'.value

   8:             'Near Mint (NM/M-)'    = $json2.'Near Mint (NM or M-)'.value

   9:             'Good (G)'             = $json2.'Good (G)'.value

  10:             'Mint (M)'             = $json2.'Mint (M)'.value

  11:             'Fair (F)'             = $json2.'Fair (F)'.value

  12:             'Good Plus (G+)'       = $json2.'Good Plus (G+)'.value

  13:             'Poor (P)'             = $json2.'Poor (P)'.value

  14:     }

  15: New-Object PSObject -Property $details 

 

The Complete Script

Here is the complete script.  Remember to insert your personal use token which you can generate by registering for a free account on the Discogs website.

   1: $releaseNo = 1845456

   2: $release = Invoke-WebRequest -uri https://api.discogs.com/releases/$releaseNo

   3: $json = ConvertFrom-Json $release.Content

   4:  

   5: $h2 = @{}

   6: $h2.Add('Authorization', 'Discogs token=<YOUR_PERSONAL_USE_TOKEN>')

   7:  

   8: $market = Invoke-WebRequest -uri https://api.discogs.com/marketplace/price_suggestions/$releaseNo -Headers $h2

   9: $json2 = ConvertFrom-Json $market.Content

  10:  

  11: $details = @{            

  12:             Artist       = $json.artists[0].name

  13:             Album        = $json.title            

  14:             Release      = $releaseNo 

  15:             CurrentDate  = Get-Date 

  16:             'Very Good (VG)'       = $json2.'Very Good (VG)'.value 

  17:             'Very Good Plus (VG+)' = $json2.'Very Good Plus (VG+)'.value

  18:             'Near Mint (NM/M-)'    = $json2.'Near Mint (NM or M-)'.value

  19:             'Good (G)'             = $json2.'Good (G)'.value

  20:             'Mint (M)'             = $json2.'Mint (M)'.value

  21:             'Fair (F)'             = $json2.'Fair (F)'.value

  22:             'Good Plus (G+)'       = $json2.'Good Plus (G+)'.value

  23:             'Poor (P)'             = $json2.'Poor (P)'.value

  24:     }

  25: New-Object PSObject -Property $details

 

In the next article

I’ll show you how to convert this basic script into a repeatable script which can process the details of hundreds of entries. 

We’ll cover off:

  • Reading from a CSV source
  • Looping through items
  • Pausing execution when errors occur
  • Writing output to CSV
  • Catering for resuming queries

Leave a comment

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.