🌞 [Other]: API to function mapping redesign #278
Description
Description
Functions consist of two, sometimes more parts, but generally its Verb-Noun, where Verb is the action carried out and noun in the object type that the action is taken on. Sometimes the noun would become more like a pathed name to what ever subresource that the action is performed on. As the GitHub API is somewhat scattered around the docs into weird groups (installations can be found under GitHub App/Apps, GitHub App/Installations, Organization/Organizations, etc), we cannot use that as the noun we use for functions.
Suggestion:
Verb mapping
| REST Method | Verb | Comments |
|---|---|---|
| GET | Get | |
| PATCH | Update, Add, Remove | Depends on the endpoint. Some of the endpoints do a patch with a .../add or /remove endpoint. |
| PUT | Set | Should be able to declare the existence and configuration of something. Must have a -PassThru to allow users to get the created/updated resource. |
| POST | New, Add | Should be creating something or maybe also starting something |
| DELETE | Remove, Uninstall, Unblock etc, | Removal of something, not too many verbs available for this. |
draft from elsewhere
PLEASE ALIGN API SPEC
Allow this for all resources, and "child resources".
Allow optionally set list of things from the parent resource as a declarative deployment of the child resources. I.e. Allow from Update-GitHubVariable to set (read declare) SelectedRepository list.
| Operation | PowerShell verb | REST Method | Why? |
|---|---|---|---|
| Create | New | Put/Post | Ability to create a resource, fail if it exists, return the object, all settings available in 'update' should be available |
| Read | Get | Get | Ability to get a list of resources when a unique identifier is not defined. |
| Update | Update | Patch | |
| Delete | Remove | Delete | |
| Declare/define | Set | Put |
Noun guidelines
Nouns should be the same based on the type of object that is the subject of the action. As an example, repositories are the same objects for users, organizations and enterprise organizations. So the noun should be Repository. If this is a get action, and with the GitHub prefix on noun, it should be Get-GitHubRepository regardless of where the resource resides.
Controlling scope and filters
With resource types that can be configured on multiple locations, the way to control where the object resides will be with the parameters that are used. In the function that can be routed to the correct api endpoint using the ParameterSets where certain parameters are mandatory.
| Function call | Comment |
|---|---|
| Get-GitHubRepository | Get all repos I have access to. That is automatically filtered depending on context, on GHE.com it only returns repos you have access to in that enterprise. |
| Get-GitHubRepository -User 'MariusStorhaug' | Gets all repos for the user 'MariusStorhaug' |
| Get-GitHubRepository -Organization 'PSModule' | Gets all repos for the org 'PSModule' |
| Get-GitHubRepository -Enterprise 'msx' | Gets all repos in the enterprise 'msx'. Same results if it is on GHE without the enterprise parameter. |
Another scenario, Installations
| Function call | Comment |
|---|---|
| Get-GitHubAppInstallation -User 'MariusStorahug' | Gets all App Installations on a given user |
| Get-GitHubAppInstallation -Organization 'PSModule' | Gets all App Installations on a given org |
| Get-GitHubAppInstallation -Enterprise 'msx' | Gets all App Installations on a given enterprise |
Point is... In PowerShell, don't include the scope details in the command name. Add it as a parameter, and imagine the scoping that default is there with the limits of the instance you are working with. GHE is a separate instance than github.com, while enterprises in GHEC (github.com) need to be specified.
Things to also read up on:
- https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md
- https://apistylebook.com/design/guidelines/
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status#client_error_responses
- https://github.com/microsoft/api-guidelines/blob/vNext/graph/GuidelinesGraph.md
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status#client_error_responses