Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Callidus2000/ARAH
This Powershell Module is a generic wrapper/helper for REST APIs.
https://github.com/Callidus2000/ARAH
Last synced: 9 days ago
JSON representation
This Powershell Module is a generic wrapper/helper for REST APIs.
- Host: GitHub
- URL: https://github.com/Callidus2000/ARAH
- Owner: Callidus2000
- License: gpl-3.0
- Created: 2021-02-23T08:19:05.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2024-07-24T13:24:06.000Z (5 months ago)
- Last Synced: 2024-08-13T07:05:09.898Z (4 months ago)
- Language: PowerShell
- Homepage:
- Size: 186 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: docs/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- jimsghstars - Callidus2000/ARAH - This Powershell Module is a generic wrapper/helper for REST APIs. (PowerShell)
README
[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![GPLv3 License][license-shield]][license-url]
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
## 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](https://github.com/PowershellFrameworkCollective/PSModuleDevelopment)
* [psframework](https://github.com/PowershellFrameworkCollective/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:
```powershell
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](https://github.com/Callidus2000/PSGitea) or [Dracoon](https://github.com/Callidus2000/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:
```powershell
$connection = Get-ARAHConnection -Url $Url -APISubPath "/api"
$connection.ContentType = "application/json;charset=UTF-8"
```
##### Example Source [Connect-Gitea.ps1](https://github.com/Callidus2000/PSGitea/blob/master/Gitea/functions/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](https://try.gitea.io/api/swagger) for "Get All Organizations"
```powershell
$apiCallParameter = @{
Connection = $Connection
method = "Get"
Path = "/v1/orgs"
}
Invoke-ARAHRequest @apiCallParameter
```
##### Example Source [Get-GiteaOrganisation.ps1](https://github.com/Callidus2000/PSGitea/blob/master/Gitea/functions/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:
```powershell
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](https://github.com/Callidus2000/PSGitea/blob/master/Gitea/functions/Invoke-GiteaAPI.ps1) uses the same base technique as Invoke-ARAHRequest but enables Paging of provided data with the help of a predefined ScriptBlock.
```powershell
function Invoke-GiteaAPI {
param (
[parameter(Mandatory)]
$Connection,
#.... example shortened
)
return Invoke-ARAHRequest @PSBoundParameters -PagingHandler 'Gitea.PagingHandler'
}
```
##### Example Source [Invoke-GiteaAPI](https://github.com/Callidus2000/PSGitea/blob/master/Gitea/functions/Invoke-GiteaAPI.ps1)
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](https://github.com/Callidus2000/ARAH/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](docs/CONTRIBUTING.md#Contributing-to-this-repository) 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](https://github.com/Callidus2000/ARAH)
## Acknowledgements
* [Friedrich Weinmann](https://github.com/FriedrichWeinmann) for his marvelous [PSModuleDevelopment](https://github.com/PowershellFrameworkCollective/PSModuleDevelopment) and [psframework](https://github.com/PowershellFrameworkCollective/psframework)
[contributors-shield]: https://img.shields.io/github/contributors/Callidus2000/ARAH.svg?style=for-the-badge
[contributors-url]: https://github.com/Callidus2000/ARAH/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/Callidus2000/ARAH.svg?style=for-the-badge
[forks-url]: https://github.com/Callidus2000/ARAH/network/members
[stars-shield]: https://img.shields.io/github/stars/Callidus2000/ARAH.svg?style=for-the-badge
[stars-url]: https://github.com/Callidus2000/ARAH/stargazers
[issues-shield]: https://img.shields.io/github/issues/Callidus2000/ARAH.svg?style=for-the-badge
[issues-url]: https://github.com/Callidus2000/ARAH/issues
[license-shield]: https://img.shields.io/github/license/Callidus2000/ARAH.svg?style=for-the-badge
[license-url]: https://github.com/Callidus2000/ARAH/blob/master/LICENSE