Command have unapproved verbs

[wsmelton]

Importing the module into a PowerShell session will always spit a warning out when there are verbs used on command names that are not part of the approved list from Microsoft/PowerShell team. It is a general practice to stick with the approved verbs that are found via Get-Verb.

A common practice to get around it and ensure the warning messages are not observed by users is to create the command in the module using an approved verb, and add the desired command name as an alias.

Output received:

[2] > ipmo C:\Modules\AkamaiPowershell\
WARNING: The names of some imported commands from the module 'AkamaiPowershell' include unapproved verbs that might make them less discoverable. To find the commands with unapproved verbs, run the Import-Module command again with the Verbose parameter. For a list of approved verbs, type Get-Verb.

[stuartio]

So this came up early in the module's history, and the feeling was that the approved verbs didn't fit into all of our scenarios (e.g. activate, purge etc.). So we took the decision to use verbs which more closely match what the function is doing but at the cost of spitting out that irritating warning. We could I guess change those functions to use approved verbs and keep the previous function name as an alias, but I worry it would make the code harder to troubleshoot since currently the filename is the function name so finding the source is quite easy.

Curious as to how other modules have solved this issue, if they have scenarios where the approved verbs don't quite fit.

[wsmelton]

Not sure how long back that history goes as I have not seen the current approved verb list not cover a command's primary action. I don't know that it is really an issue to solve directly because majority of module authors just work with the approved verbs.

Purge --> Remove Activate --> Publish (or Register) List --> Get

[stuartio]

So as I understand the list of approved verbs is there to make functions more discoverable for users. However. the approach we have used is to use the verbs (mostly) that are referenced in the Akamai API docs, and are used within the Akamai Control Centre UI.

So, while Publish-Property would be similar enough to Activate-Property, since "activate" is the verb generally used when discussing that operation with Akamai I would argue that using Publish would make the function less discoverable. There are certainly some we could do, List- for example, though my main reasons for that one were a) List is how it the operation is described in the docs, and b) a Get- command (singular) would only differ from its Get- plural equivalent by a single letter, so would be easier to make a mistake.

Some of the functions (most of the ones in the Shared directory) which have unknown verbs we could simply not export (since they aren't really meant to be used directly) but others, such as the NSAPI functions which are 1 to 1 with the actual operation names, it would definitely make it harder to find if we changed the names.

Have you found the functions to be difficult to discover using the unapproved verbs? Does anyone else who might be reading this feel strongly one way or the other?

We can certainly look at some kind of sanitisation of naming structure for v2 when it comes along.

[rmbolger]

I've only really used the module in the context of DNS services and infrequently enough that I usually need to refresh my memory about function names using something like Get-Command -Module akamaipowershell. But I do recall being mildly annoyed with conventions like List-Zone vs Get-Zones.

In a totally idealistic world, I shouldn't need to know or care how the underlying API actually functions. I just know that there are DNS zones that I want to get all of or some of. And usually that would involve calling some variation of Get-Zone or Get-AkamaiZone where getting the list or getting an individual or subset are combined into the same function differentiated by parameters. Think about native commands like Get-ChildItem or Get-Process.

# Get all processes
Get-Process

# Get a specific process
Get-Process -Id 0

# Get all child items
Get-ChildItem

# Get a subset of child items
Get-ChildItem -Filter *.txt

Obviously, the shape of the API can make this more difficult if it doesn't nicely map to PowerShell's Verb-Noun standards like those bulk zone delete functions I submitted a while back. But again in an idealistic world, it's ostensibly the author's job to work around the API limitations and make those abstractions work.

As is usually the case, reality isn't ideal...so it's always a balancing game. And I'm sure people would have something that works non-ideally versus nothing at all...particularly from an author who is volunteering their time for no pay.

[stuartio]

Thanks for that Ryan. There are a few functions which abstract multiple API endpoints behind a single function name, but it is pretty rare. However, your point about combining the List and Get endpoints together into a single Get is an intriguing one which I really like.

All the existing List- functions already have a Get- equivalent, but they are always separate calls from the single Get- functions. Combining them would be a good idea, which I will include in the planning phase for a new major release, but it will take some re-architecting of several parts of the approach.

[stuartio]

Closing this issue. Approved verbs is a core design tenet of v2, which will hopefully release this year