Application Lifecycle Management (ALM) APIs

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 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 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 PnP Community channels.

REST API

Tip

ALM APIs are also supported for the site collection app catalog. URLs for the site collection app catalog operations are exactly the same, but you can change the tenantappcatalog to sitecollectionappcatalog. Notice also that you will need to enable the 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 app catalog site.

url: /_api/web/tenantappcatalog/Add(overwrite=true, url='test.txt')
method: POST
Authorization: Bearer <access token>
X-RequestDigest: <form digest>
Accept: 'application/json;odata=nometadata'
binaryStringRequestBody: true
body: 'byte array of the file'

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 app catalog site.

url: /_api/web/tenantappcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Deploy
method: POST
Authorization: Bearer <access token>
X-RequestDigest: <form digest>
Accept: 'application/json;odata=nometadata'
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 app catalog

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
method: POST
Authorization: Bearer <access token>
X-RequestDigest: <form digest>
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 app catalog

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
method: POST
Authorization: Bearer <access token>
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 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
method: GET
Authorization: Bearer <access token>
Accept: 'application/json;odata=nometadata'

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 app catalog.

url: /_api/web/tenantappcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')
method: GET
Authorization: Bearer <access token>
Accept: 'application/json;odata=nometadata'

Install solution package from the app catalog to a SharePoint site

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
method: POST
Authorization: Bearer <access token>
X-RequestDigest: <form digest>
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 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
method: POST
Authorization: Bearer <access token>
X-RequestDigest: <form digest>
Accept: 'application/json;odata=nometadata'

Uninstall solution packages from the SharePoint site

This REST call can be executed in the context of the site where the uninstall operation should happen.

url: /_api/web/tenantappcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Uninstall
method: POST
Authorization: Bearer <access token>
X-RequestDigest: <form digest>
Accept: 'application/json;odata=nometadata'

Note

When you use the REST API to uninstall a solution package from the site, it is not relocated to the recycle bin.

SharePoint PnP PowerShell cmdlets

By using PnP PowerShell, 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 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:

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:

Publish-PnPApp -Identity <app id> -SkipFeatureDeployment -Scope Tenant

Note

Use the SkipFeatureDeployment flag to allow an app that was developed for tenant-wide deployment to be actually available as a tenant-wide deployed app.

Remove the app from the app catalog

To remove an app added earlier, use the following cmdlet:

Remove-PnPApp -Identity <app id> -Scope Tenant

Use apps on your site

After the app is added to the app catalog and published, you can install the app to your site:

Install-PnPApp -Identity <app id> -Scope Tenant

To upgrade the app:

Update-PnPApp -Identity <app id> -Scope Tenant

To uninstall the app from your site:

Uninstall-PnPApp -Identity <app id> -Scope Tenant

Note

When you uninstall an app from your site, the app is completely deleted, so it does not end up in the site's recycle bin.

Know which apps are there for you to use

You can get a list of apps that can be added to the site by using:

Get-PnPApp -Scope Tenant

Office 365 CLI commands to add, deploy, and manage SharePoint apps cross-platform

Using the Office 365 CLI, you can automate deploying, publishing, installing, upgrading, and retracting your apps. The Office 365 CLI is a cross-platform command-line interface that can be used on any platform, including Windows, MacOS, and Linux. To learn more about these commands, see the following sections.

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. Use the add command to do this:

spo app add --filePath ./spfx.sppkg

Once added, you need to continue with publishing your app, effectively making the app available to be used by the users of your tenant. Use the deploy command to do this:

spo app deploy --id <app id> --skipFeatureDeployment

Note

Use the SkipFeatureDeployment flag to allow an app that was developed for tenant-wide deployment to be actually available as a tenant-wide deployed app.

Remove the app from the app catalog

You may want to remove an app that you added earlier, and you can do this by using the remove command:

spo app remove --id <app id>

Use apps on your site

After the app is added to the app catalog and published, you can install the app to your site by using the install command:

spo app install --id <app id> --siteUrl <url>

To upgrade the app, use the upgrade command:

spo app upgrade --id <app id> --siteUrl <url>

To uninstall the app from your site, use the uninstall command:

spo app uninstall --id <app id> --siteUrl <url>

Note

When you uninstall an app from your site, the app is completely deleted, so it will not end up in the site's recycle bin.

List and get apps in the app catalog

You can see what apps have been added to the app catalog by using the list command:

spo app list

You can get a single app's details by using the get command:

spo app get --id <app id>

See also