Adding notes on the site collection app catalog ALM API support

Author: VesaJuvonen

docs/apis/alm-api-for-spfx-add-ins.md

@@ -1,7 +1,7 @@
 ---
 title:  Application Lifecycle Management (ALM) APIs 
 description: ALM APIs provide simple APIs to manage deployment of your SharePoint Framework solutions and add-ins across your tenant.
-ms.date: 02/08/2018
+ms.date: 04/06/2018
 ms.prod: sharepoint
 ms.assetid: fdf7ecb2-8851-425b-b058-3285fba77b68
 ---
@@ -10,30 +10,30 @@ ms.assetid: fdf7ecb2-8851-425b-b058-3285fba77b68
 
 ALM APIs provide simple APIs to manage deployment of your SharePoint Framework solutions and add-ins across your tenant. ALM APIs support the following capabilities:
 
-- Add SharePoint Framework solution or SharePoint Add-in to tenant app catalog.
-- Remove SharePoint Framework solution or SharePoint Add-in from tenant app catalog.
-- Enable SharePoint Framework solution or SharePoint Add-in to be available for installation in tenant app catalog.
-- Disable SharePoint Framework solution or SharePoint Add-in not to be available for installation in tenant app catalog.
-- Install SharePoint Framework solution or SharePoint Add-in from tenant app catalog to a site.
-- Upgrade SharePoint Framework solution or SharePoint Add-in to a site, which has a newer version available in the tenant app catalog.
+- Add SharePoint Framework solution or SharePoint Add-in to tenant or site collection app catalog.
+- Remove SharePoint Framework solution or SharePoint Add-in from tenant or site collection app catalog.
+- Enable SharePoint Framework solution or SharePoint Add-in to be available for installation in tenant or site collection app catalog.
+- Disable SharePoint Framework solution or SharePoint Add-in not to be available for installation in tenant or site collection app catalog.
+- Install SharePoint Framework solution or SharePoint Add-in from tenant or site collection app catalog to a site.
+- Upgrade SharePoint Framework solution or SharePoint Add-in to a site, which has a newer version available in the tenant or site collection app catalog.
 - Uninstall SharePoint Framework solution or SharePoint Add-in from the site.
-- List all and get details about SharePoint Framework solutions or SharePoint Add-ins in the tenant app catalog.
+- List all and get details about SharePoint Framework solutions or SharePoint Add-ins in the tenant or site collection app catalog.
 
 ALM APIs can be used to perform exactly the same operations that are available from a UI perspective. When these APIs are used, all typical actions are performed. Following are some of the characteristics of ALM APIs:
 
 - `Install` and `UnInstall` events are being fired for provider-hosted add-ins when corresponding operations occur.
 - ALM APIs support app-only-based operations.
 
-ALM APIs are natively provided by using REST APIs, but there are additional CSOM extensions, PowerShell cmdlets, and the cross-platform Office 365 CLI available through SharePoint Patterns and Practices.
-
-> [!NOTE] 
-> ALM APIs are not currently supported for the [site collection app catalog](../general-development/site-collection-app-catalog.md). Support will be added in early 2018.
+ALM APIs are natively provided by using REST APIs, but there are additional CSOM extensions, PowerShell cmdlets, and the cross-platform Office 365 CLI available through SharePoint PnP Community channels.
 
 ## REST API
 
-### Add solution package to the tenant app catalog
+> [!TIP] 
+> ALM APIs are also  supported for the [site collection app catalog](../general-development/site-collection-app-catalog.md). URLs for the site collection app catalog operations are exactly the same, but you can change the `tenantappcatalog` as `sitecollectionappcatalog`. Notice also that you will need to enable site collection app catalog in your site collection or you will get an exception when trying to use these APIs.
+
+### Add solution package to the app catalog
 
-This API is designed to be executed in the context of the tenant app catalog site.
+This API is designed to be executed in the context of the app catalog site.
 
 ```
 url: /_api/web/tenantappcatalog/Add(overwrite=true, url='test.txt')
@@ -45,9 +45,9 @@ binaryStringRequestBody: true
 body: 'byte array of the file'
 ```
 
-### Deploy solution packages in the tenant app catalog
+### Deploy solution packages in the app catalog
 
-This enables the solution to be available to install to specific sites. This API is designed to be executed in the context of the tenant app catalog site.
+This enables the solution to be available to install to specific sites. This API is designed to be executed in the context of the app catalog site.
 
 ```
 url: /_api/web/tenantappcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Deploy
@@ -61,9 +61,9 @@ Content-Type: 'application/json;odata=nometadata;charset=utf-8'
 > [!NOTE]
 > This operation is required to be completed after Add, before you can install packages to specific sites. 
 
-### Retract solution packages in the tenant app catalog
+### Retract solution packages in the app catalog
 
-This retracts the solution to be available from the sites. This API is designed to be executed in the context of the tenant app catalog site.
+This retracts the solution to be available from the sites. This API is designed to be executed in the context of the app catalog site.
 
 ```
 url: /_api/web/tenantappcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Retract
@@ -76,9 +76,9 @@ Accept: 'application/json;odata=nometadata'
 > [!NOTE]
 > If you run this operation after you have installed solutions to the site, they stop working because the solution is disabled from the tenant level.
 
-### Remove solution packages from the tenant app catalog
+### Remove solution packages from the app catalog
 
-This API is designed to be executed in the context of the tenant app catalog site.
+This API is designed to be executed in the context of the app catalog site.
 
 ```
 url: /_api/web/tenantappcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Remove
@@ -90,9 +90,9 @@ Accept: 'application/json;odata=nometadata'
 > [!NOTE]
 > If the Retract operation is not performed before the Remove operation, the solution is automatically retracted.
 
-### List available packages from the tenant app catalog
+### List available packages from the app catalog
 
-Use this REST API for getting a list of available SharePoint Framework solutions or add-ins in the tenant app catalog.
+Use this REST API for getting a list of available SharePoint Framework solutions or add-ins in the app catalog.
 
 ```
 url: /_api/web/tenantappcatalog/AvailableApps
@@ -101,9 +101,9 @@ Authorization: Bearer <access token>
 Accept: 'application/json;odata=nometadata'
 ```
 
-### Get details about individual solution packages in the tenant app catalog
+### Get details about individual solution packages in the app catalog
 
-Use this REST API for getting details about individual SharePoint Framework solutions or add-ins available in the tenant app catalog.
+Use this REST API for getting details about individual SharePoint Framework solutions or add-ins available in the app catalog.
 
 ```
 url: /_api/web/tenantappcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')
@@ -112,9 +112,9 @@ Authorization: Bearer <access token>
 Accept: 'application/json;odata=nometadata'
 ```
 
-### Install solution package from the tenant app catalog to a SharePoint site
+### Install solution package from the app catalog to a SharePoint site
 
-Install a solution package with a specific identifier from the tenant app catalog to the site based on URL context. This REST call can be executed in the context of the site where the install operation should happen.
+Install a solution package with a specific identifier from the app catalog to the site based on URL context. This REST call can be executed in the context of the site where the install operation should happen.
 
 ```
 url: /_api/web/tenantappcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Install
@@ -126,7 +126,7 @@ Accept: 'application/json;odata=nometadata'
 
 ### Upgrade solution packages on the SharePoint site
 
-Upgrade a solution package from the site to a newer version available in the tenant app catalog. This REST call can be executed in the context of the site where the upgrade operation should happen.
+Upgrade a solution package from the site to a newer version available in the app catalog. This REST call can be executed in the context of the site where the upgrade operation should happen.
 
 ```
 url: /_api/web/tenantappcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Upgrade
@@ -155,17 +155,20 @@ Accept: 'application/json;odata=nometadata'
 
 By using [PnP PowerShell](https://docs.microsoft.com/en-us/powershell/sharepoint/sharepoint-pnp/sharepoint-pnp-cmdlets?view=sharepoint-ps), you can automate deploying, publishing, installing, upgrading, and retracting your apps. 
 
+> [!NOTE]
+> Support for scope option was released on the April 2018 release of PnP PowerShell.
+
 ### Add and publish your app to the app catalog
-Adding your app (.sppkg file, .app file) to the tenant app catalog is a prerequisite to making your app available for use on your SharePoint sites. You can do this by using the following cmdlet:
+Adding your app (.sppkg file, .app file) to the app catalog is a prerequisite to making your app available for use on your SharePoint sites. You can do this by using the following cmdlet:
 
 ```PowerShell
-Add-PnPApp -Path ./myapp.sppkg
+Add-PnPApp -Path ./myapp.sppkg -Scope Tenant
 ```
 
 Once added, you need to continue with publishing your app, effectively making the app available to be used by the users of your tenant. The following PnP PowerShell cmdlet shows how this can be done:
 
 ```PowerShell
-Publish-PnPApp -Identity <app id> -SkipFeatureDeployment
+Publish-PnPApp -Identity <app id> -SkipFeatureDeployment -Scope Tenant
 ```
 
 
@@ -179,7 +182,7 @@ Publish-PnPApp -Identity <app id> -SkipFeatureDeployment
 To remove an app added earlier, use the following cmdlet:
 
 ```PowerShell
-Remove-PnPApp -Identity <app id>
+Remove-PnPApp -Identity <app id> -Scope Tenant
 ```
 
 
@@ -188,20 +191,20 @@ Remove-PnPApp -Identity <app id>
 After the app is added to the app catalog and published, you can install the app to your site:
 
 ```PowerShell
-Install-PnPApp -Identity <app id>
+Install-PnPApp -Identity <app id> -Scope Tenant
 ```
 
 
 To upgrade the app:
 
 ```PowerShell
-Update-PnPApp -Identity <app id>
+Update-PnPApp -Identity <app id> -Scope Tenant
 ```
 
 To uninstall the app from your site:
 
 ```PowerShell
-Uninstall-PnPApp -Identity <app id>
+Uninstall-PnPApp -Identity <app id> -Scope Tenant
 ```
 
 
@@ -215,7 +218,7 @@ Uninstall-PnPApp -Identity <app id>
 You can get a list of apps that can be added to the site by using:
 
 ```PowerShell
-Get-PnPApp
+Get-PnPApp -Scope Tenant
 ```
 
 ## Office 365 CLI commands to add, deploy, and manage SharePoint apps cross-platform