Update api calls for Find and Install

src/code/IFindPSResource.cs

@@ -28,32 +28,39 @@ public interface IFindPSResource
     /// Name: supports wildcards
     /// Type: Module, Script, Command, DSCResource (can take multiple)
     /// Examples: Search -Type Module -Repository PSGallery
-    ///           Search "Az*" -Type Module -Repository PSGallery
-    /// - No prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsLatestVersion&searchTerm='tag:Module'
-    /// - Include prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsAbsoluteLatestVersion&searchTerm='tag:Module'&includePrerelease=true
+    ///           Search -Type Module -Name "Az*" -Repository PSGallery
+    /// TODO: discuss consolidating Modules and Scripts endpoints (move scripts to modules endpoint)
+    /// TODO Note: searchTerm is tokenized by whitespace.
+    /// - No prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsLatestVersion&searchTerm='Az* tag:PSModule'
+    /// - Include prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsLatestVersion&searchTerm='az* tag:PSScript'&includePrerelease=true
     /// </summary>
     PSResourceInfo FindTypes(ResourceType packageResourceType, string packageName, PSRepositoryInfo repository, bool includePrerelease);
 
     /// <summary>
     /// Find method which allows for searching for command names and returns latest version of matching packages.
-    /// Name: supports wildcards
+    /// Name: supports wildcards.
     /// Examples: Search -Name "Command1", "Command2" -Repository PSGallery
+    /// - No prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsLatestVersion&searchTerm='Az* tag:PSCommand_Command1 tag:PSCommand_Command2'
+    /// - Include prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsLatestVersion&searchTerm='Az* tag:PSCommand_Command1 tag:PSCommand_Command2'&includePrerelease=true
     /// </summary>
     PSResourceInfo FindCommandName(string[] commandNames, PSRepositoryInfo repository, bool includePrerelease);
 
     /// <summary>
     /// Find method which allows for searching for DSC Resource names and returns latest version of matching packages.
-    /// Name: supports wildcards
+    /// Name: Support wildcards.
     /// Examples: Search -Name "DSCResource1", "DSCResource2" -Repository PSGallery
-    PSResourceInfo FindDSCResourceName(string[] dscResourceName, PSRepositoryInfo repository, bool includePrerPSResourceInfoPSResourceInfoelease);
+    /// - No prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsLatestVersion&searchTerm='Az* tag:PSDSCResource_DSCResource1 tag:PSDSCResource_DSCResource2'
+    /// - Include prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsLatestVersion&searchTerm='Az* tag:PSDSCResource_DSCResource1 tag:PSDSCResource_DSCResource2'&includePrerelease=true
+    PSResourceInfo FindDSCResourceName(string[] dscResourceName, PSRepositoryInfo repository, bool includePrerelease);
 
     /// <summary>
     /// Find method which allows for searching for single name and returns latest version.
     /// Name: no wildcard support
     /// Examples: Search "PowerShellGet"
     /// API call: 
-    /// - No prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsLatestVersion&searchTerm='PowerShellGet'
-    /// - Include prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsAbsoluteLatestVersion&searchTerm='PowerShellGet'&includePrerelease=true
+    /// - No prerelease: http://www.powershellgallery.com/api/v2/FindPackagesById()?id='PowerShellGet'
+    /// - Include prerelease: http://www.powershellgallery.com/api/v2/FindPackagesById()?id='PowerShellGet'
+    /// Implementation Note: Need to filter further for latest version (prerelease or non-prerelease dependening on user preference)
     /// </summary>
     PSResourceInfo FindName(string packageName, PSRepositoryInfo repository, bool includePrerelease);
 
@@ -64,6 +71,7 @@ public interface IFindPSResource
     /// API call: 
     /// - No prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsLatestVersion&searchTerm='az*'
     /// - Include prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsAbsoluteLatestVersion&searchTerm='az*'&includePrerelease=true
+    /// Implementation Note: filter additionally and verify ONLY package name was a match.
     /// </summary>
     PSResourceInfo FindNameGlobbing(string packageName, PSRepositoryInfo repository, bool includePrerelease);
 
@@ -73,6 +81,8 @@ public interface IFindPSResource
     /// Version: supports wildcards
     /// Examples: Search "PowerShellGet" "[3.0.0.0, 5.0.0.0]"
     ///           Search "PowerShellGet" "3.*"
+    /// API Call: http://www.powershellgallery.com/api/v2/FindPackagesById()?id='PowerShellGet'
+    /// Implementation note: Returns all versions, including prerelease ones. Later (in the API client side) we'll do filtering on the versions to satisfy what user provided.
     /// </summary>
     PSResourceInfo FindVersionGlobbing(string packageName, VersionRange versionRange, PSRepositoryInfo repository, bool includePrerelease);
 
@@ -84,8 +94,9 @@ public interface IFindPSResource
     /// API call: http://www.powershellgallery.com/api/v2/Packages(Id='PowerShellGet', Version='2.2.5')
     /// </summary>
     PSResourceInfo FindVersion(string packageName, NuGetVersion version, PSRepositoryInfo repository);
-
+    
     /// <summary>
+    /// *** we will not support this scenario ***
     /// Find method which allows for searching for single name with wildcards with version range.
     /// Name: supports wildcards
     /// Version: support wildcards
@@ -95,6 +106,7 @@ public interface IFindPSResource
     PSResourceInfo FindNameGlobbingAndVersionGlobbing(string packageName, VersionRange versionRange, PSRepositoryInfo repository, bool includePrerelease);
 
     /// <summary>
+    /// *** we will not support this scenario ***
     /// Find method which allows for searching for single name with wildcards with specific version.
     /// Name: supports wildcards
     /// Version: no wildcard support
@@ -103,16 +115,15 @@ public interface IFindPSResource
     PSResourceInfo FindNameGlobbingAndVersion(string packageName, NuGetVersion version, PSRepositoryInfo repository);
 
     /// <summary>
+    /// *** Note: we would just iterate through the names client side and call FindName() or FindNameGlobbing() *** 
     /// Find method which allows for searching for multiple names and returns latest version for each.
     /// Name: supports wildcards
     /// Examples: Search "PowerShellGet", "Package*", "PSReadLine"
-    /// API call: 
-    /// - No prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsLatestVersion&searchTerm='PSReadLine, Package*'
-    /// - Include prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsAbsoluteLatestVersion&searchTerm='PSReadLine, Package*'&includePrerelease=true
     /// </summary>
     PSResourceInfo FindNamesGlobbing(string[] packageNames, PSRepositoryInfo repository, bool includePrerelease);
 
     /// <summary>
+    /// *** we will not support this scenario ***
     /// Find method which allows for searching for multiple names with specific version.
     /// Name: supports wildcards
     /// Version: no wildcard support
@@ -121,13 +132,15 @@ public interface IFindPSResource
     PSResourceInfo FindNamesGlobbingAndVersion(string[] packageNames, NuGetVersion version, PSRepositoryInfo repository);
 
     /// <summary>
+    /// *** Note: would just iterate through names client side, and call FindVersionGlobbing() for each and discard (error) for name with globbing) ***
     /// Find method which allows for searching for multiple names with version range.
     /// Name: supports wildcards
     /// Version: support wildcards
-    /// Examples: Search "PowerShellGet", "Package*", "PSReadLine" "[3.0.0.0, 5.0.0.0]"
-    ///           Search "PowerShellGet", "Package*", "PSReadLine" "3.*"
+    /// Examples: Search "PowerShellGet", "Package*", "PSReadLine" "[3.0.0.0, 5.0.0.0]" --> do it for first, write error for second, do it for third
+    ///           Search "PowerShellGet", "Package*", "PSReadLine" "3.*" --> do it for first, write error for second, do it for third
+    ///           Search "Package*", "PSReadLin*" "3.*" --> not supported
     /// </summary>
-    PSResourceInfo FindNamesGlobbingAndVersionGlobbing(string[] packageNames, VersionRange versionRange, PSRepositoryInfo repository, bool includePrerelease); 
+    PSResourceInfo FindNamesAndVersionGlobbing(string[] packageNames, VersionRange versionRange, PSRepositoryInfo repository, bool includePrerelease); 
 
     #endregion
 }

src/code/IInstallPSResource.cs

@@ -9,6 +9,8 @@ public interface IInstallPSResource
     /// Installs specific package.
     /// Name: no wildcard support.
     /// Examples: Install "PowerShellGet"
+    /// Implementation Note: if prerelease: call IFindPSResource.FindName()
+    ///                      if not prerelease: https://www.powershellgallery.com/api/v2/package/Id (Returns latest stable)
     /// </summary>
     PSResourceInfo InstallName(string pkgName, PSRepositoryInfo repository, bool includePrerelease);
 
@@ -18,10 +20,12 @@ public interface IInstallPSResource
     /// Version: no wildcard support.
     /// Examples: Install "PowerShellGet" -Version "3.0.0.0"
     ///           Install "PowerShellGet" -Version "3.0.0-beta16"
+    /// API Call: https://www.powershellgallery.com/api/v2/package/Id/version (version can be prerelease)
     /// </summary>    
     PSResourceInfo InstallVersion(string pkgName, NuGetVersion version, PSRepositoryInfo repository);
 
     /// <summary>
+    /// Implementation note: We'd call IFindPSResource.FindVersionGlobbing() first and InstallVersion().
     /// Installs latest package within version range provided.
     /// Name: no wildcard support.
     /// Version: supports wilcard.