The search code method of the GitHub REST API is used to demonstrate how arguments can be passed to a REST method.

The documentation for the method is found in the following API reference: https://developer.github.com/v3/search/#search-code.

The following example uses the search code method by building a query string and appending that to the end of the URL. The search looks for occurrences of the Get-Content term in PowerShell language files in the PowerShell repository. The search term is therefore the following:

Get-Content language:powershell repo:powershell/powershell

Converting the example from the documentation, the URL required is as follows. Spaces may be replaced by + when encoding the URL:

https://api.github.com/search/code?q=Get-Content+language:powershell+repo:powershell/powershell

In Windows PowerShell, which can use the HttpUtility type within the System.Web assembly, the task of encoding the URL can be simplified:

using assembly System.Web

$queryString = [System.Web.HttpUtility]::ParseQueryString('')
$queryString.Add('q', 'Get-Content language:powershell repo:powershell/powershell')
Invoke-RestMethod ('https://api.github.com/search/code?{0}' -f $queryString)

Running $queryString.ToString() will show that the colon character has been replaced by %3, and the forward slash in the repository name by %2.

PowerShell Core cannot use the HttpUtility type, which would leave an author trying to find a means of properly encoding the URL. However, the arguments for the search do not necessarily have to be passed as a query string. Instead, a body for the request may be set, as shown here: 

Invoke-RestMethod -Uri https://api.github.com/search/code -Body @{
    q = 'Get-Content language:powershell repo:powershell/powershell'
}

Invoke-RestMethod converts the body (a hashtable) to JSON and handles any encoding required. The result of the search is the same whether the body is set or a query string is used.

In both cases, details of issues are held within the items property of the response:

Invoke-RestMethod -Uri https://api.github.com/search/code -Body @{
    q = 'Get-Content language:powershell repo:powershell/powershell'
} | Select-Object -ExpandProperty items | Select-Object number, title

This pattern, where the actual results are nested under a property in the response, is frequently seen with REST interfaces. Exploration is often required.

It is critical to note that REST interfaces are case-sensitive; using a parameter named Q would result in an error message, as shown here:

PS> Invoke-RestMethod -Uri https://api.github.com/search/code -Body @{
>>     Q = 'Get-Content language:powershell repo:powershell/powershell'
>> }
Invoke-RestMethod : {"message":"Validation Failed","errors":[{"resource":"Search","field":"q","code":"missing"}],"documentation_url":"https://developer.github.com/v3/search"}
At line:1 char:1
+ Invoke-RestMethod -Uri https://api.github.com/search/code -Body @{
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : InvalidOperation: (Method: GET, Re...rShell/6.1.0
}:HttpRequestMessage) [Invoke-RestMethod], HttpResponseException
+ FullyQualifiedErrorId : WebCmdletWebResponseException,Microsoft.PowerShell.Commands.InvokeRestMethodCommand

The GitHub API returns an easily understood error message in this case. This will not be true of all REST APIs; it is not uncommon to see a generic error returned by an API. An API may return a simple HTTP 400 error and leave it to the user or developer to figure out what went wrong.