ARAH: Advanced REST API Helper

This Powershell Module is a generic wrapper/helper for REST APIs.
Explore the docs »

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgements

About The Project

This Powershell Module is a generic wrapper/helper for REST APIs. The code has started in my Dracoon project. To use the power of the created helper functions within other API centric modules I've created ARAH.

Built With

• PSModuleDevelopment
• psframework

Getting Started

To get a local copy up and running follow these simple steps.

Prerequisites

All prerequisites will be installed automatically.

Installation

The releases are published in the Powershell Gallery, therefor it is quite simple:

Install-Module ARAH -Force -AllowClobber

The AllowClobber option is currently necessary because of an issue in the current PowerShellGet module. Hopefully it will not be needed in the future any more.

Usage

The module is a wrapper for the REST API. If you want to learn how it works take a look at my Gitea Wrapper or Dracoon. If you want to use it for creating your own API wrapper here is the quick roundup of the necessary steps, with links to the corresponding Gitea scripts as this is the simpler module.

Create your Connection function

Every API Call needs information for authentication and maybe additional headers. All this is stored in an [ARAHConnection] object. Create this base-object and add the necessary information to it:

$connection = Get-ARAHConnection -Url $Url -APISubPath "/api"
$connection.ContentType = "application/json;charset=UTF-8"

Example Source Connect-Gitea.ps1

This object should be passed to every API function you specify.

Create your API Functions

This module provides the Invoke-ARAHRequest function for invoking API endpoints on a parameter base. All you have to do to access an API function is to tell it where what information is needed. For example accessing the Gitea API for "Get All Organizations"

$apiCallParameter = @{
    Connection   = $Connection
    method       = "Get"
    Path         = "/v1/orgs"
}

Invoke-ARAHRequest @apiCallParameter

Example Source Get-GiteaOrganisation.ps1

This takes away all the clobber of checking parameters for $null values and furthermore.

Important: AutoCreation available!

Since v1.1.0 it is possible to create API functions based on an existing Swagger Spec. Until documented in detail take a look a the integrated help:

Get-Help New-ARAHSwaggerFunction

Optional Step: Create your own Invoke-* Proxy

If you have got the need to extend the functionality of Invoke-ARAHRequest (e.g. modifying the request before it is sent) you can create your own proxy function with defined endpoints. For example the Invoke-GiteaAPI uses the same base technique as Invoke-ARAHRequest but enables Paging of provided data with the help of a predefined ScriptBlock.

function Invoke-GiteaAPI {
    param (
        [parameter(Mandatory)]
        $Connection,
        #.... example shortened
    )
    return Invoke-ARAHRequest @PSBoundParameters -PagingHandler 'Gitea.PagingHandler'
}

Example Source Invoke-GiteaAPI

The code for the PagingHandler is defined in \Gitea\internal\scriptblocks\Gitea-PagingHandler.ps1 and performs all the nasty page/limit work. As a result every Invoke-GiteaAPI call can return all results not regarding how large the default limit is set.

Roadmap

New features will be added if any of my scripts need it ;-)

See the open issues for a list of proposed features (and known issues).

If you need a special function feel free to contribute to the project.

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated. For more details please take a look at the CONTRIBUTE document

Short stop:

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the GNU GENERAL PUBLIC LICENSE version 3. See LICENSE for more information.

Contact

Project Link: https://github.com/Callidus2000/ARAH

Acknowledgements

• Friedrich Weinmann for his marvelous PSModuleDevelopment and psframework