Skip to content

Commit 8b2fb1c

Browse files
andrewconnellandrewconnell
authored
Merge pull request SharePoint#9528 from RongqiZ/main
update the addin apis to accept full url as input
2 parents 7fc1dc6 + 2966501 commit 8b2fb1c

File tree

1 file changed

+52
-34
lines changed

1 file changed

+52
-34
lines changed

‎docs/apis/addin-management-apis.md

Lines changed: 52 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ For more information about SharePoint Add-in, see [SharePoint Add-ins](../sp-add
2828

2929
## Get available Add-ins in sites
3030

31-
This API will return the Add-ins that could be used on the given sites. This contains two kinds of install, one is the Add-in installed on the site.
31+
This API will return the Add-ins that could be used on the given sites. This contains two kinds of install, one is the Add-in installed on the site.
3232
The other is the Add-in installed on the tenant level app catalog site, and it matches the conditions to use the Add-in.
3333
For more information, see [Tenancies and deployment scopes for SharePoint Add-ins](../sp-add-ins/tenancies-and-deployment-scopes-for-sharepoint-add-ins.md).
3434

@@ -42,13 +42,16 @@ POST {adminSiteUrl}/_api/web/AvailableAddIns
4242

4343
### Request body
4444

45-
| Name | Required | Type | Description |
46-
|--------------------|----------|----------|-------------------------------------------------------------------------------------------------------|
47-
| serverRelativeUrls | yes | string[] | List of the server relative url of sites that want to get the available Add-ins. Maximum size is 500. |
45+
| Name | Required | Type | Description |
46+
|--------------------|----------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------|
47+
| serverRelativeUrls | no | string[] | List of the server relative url of sites that want to get the available Add-ins. Maximum size is 500. |
48+
| urls | no | string[] | List of the url of sites that want to get the available Add-ins, both server relative url and absolute url are acceptable. Maximum size is 500. |
49+
50+
When urls is not null, serverRelativeUrls will be disregarded.
4851

4952
### Responses
5053

51-
| Name | Type | Description |
54+
| Name | Type | Description |
5255
|-----------------------------|--------------------------------|--------------------------------------------------------------------------------------|
5356
| addins | SPAddinInstanceInfo[] | Available Add-in instance object. |
5457
| errorsWithServerRelativeUrl | SPErrorWithServerRelativeUrl[] | Server relative urls that failed to get available add-ins and corresponding reasons. |
@@ -88,7 +91,7 @@ POST {adminSiteUrl}/_api/web/AvailableAddIns
8891

8992
| Name | Type | Description |
9093
|-------------------|--------|--------------------------------------------------------|
91-
| serverRelativeUrl | string | The serverRelativeUrl in the request body. |
94+
| serverRelativeUrl | string | The serverRelativeUrl or url in the request body. |
9295
| errorMessage | string | The error message why fetch the site's Add-ins failed. |
9396

9497
## Get Add-in permissions in site collections
@@ -111,13 +114,15 @@ POST {adminSiteUrl}/_api/web/AddinPermissions
111114

112115
#### SPAddinPermissionRequest
113116

114-
| Name | Type | Description |
115-
|-------------------|----------|--------------------------------------------------------------------------------------------------------------------------------|
116-
| serverRelativeUrl | string | The server relative url of the site collection. It will return site collection scope permissions of the given site collection. |
117-
| appIdentifiers | string[] | The identifier list of the Add-ins. |
117+
| Name | Type | Description |
118+
|-------------------|----------|-------------------------------------------------------------------------------------------|
119+
| serverRelativeUrl | string | The server relative url of the site collection. |
120+
| url | string | The url of the site collection, both server relative url and absolute url are acceptable. |
121+
| appIdentifiers | string[] | The identifier list of the Add-ins. |
118122

119-
### Responses
123+
The serverRelativeUrl and url can't be both null. If both serverRelativeUrl and url are provided, the url will be used.
120124

125+
### Responses
121126
| Name | Type | Description |
122127
|------------------|-------------------------------|-----------------------------------------------------------------------|
123128
| addinPermissions | SPAddinPermissionInfo[] | The returned permissions. |
@@ -131,6 +136,7 @@ POST {adminSiteUrl}/_api/web/AddinPermissions
131136
| siteCollectionScopedPermissions | SPSiteCollectionScopedPermissionInfo[] | This is the permissions grant in site collection scope level. |
132137
| appIdentifier | string | The identifier of the Add-in. |
133138
| serverRelativeUrl | string | The server relative url of the site collection. |
139+
| absoluteUrl | string | The absolute url of the site collection. |
134140
| allowAppOnly | bool | This identifies if the Add-in allows app only mode. For more information, see [Add-in authorization policy types in SharePoint](../sp-add-ins/add-in-authorization-policy-types-in-sharepoint.md). |
135141

136142
#### SPTenantScopedPermissionInfo
@@ -155,11 +161,11 @@ POST {adminSiteUrl}/_api/web/AddinPermissions
155161

156162
#### SPAddinPermissionFailedInfo
157163

158-
| Name | Type | Description |
159-
|-------------------|--------|-----------------------------------------------------------|
160-
| serverRelativeUrl | string | The server relative url of the site collection. |
161-
| appIdentifier | string | The identifier list of the Add-in. |
162-
| errorMessage | string | The error message why fetch the Add-in permission failed. |
164+
| Name | Type | Description |
165+
|-------------------|--------|-----------------------------------------------------------------|
166+
| serverRelativeUrl | string | The server relative url or absolute url of the site collection. |
167+
| appIdentifier | string | The identifier list of the Add-in. |
168+
| errorMessage | string | The error message why fetch the Add-in permission failed. |
163169

164170
## Get tenant ACS service principals
165171

@@ -210,9 +216,12 @@ POST {adminSiteUrl}/_api/web/GetAddinPrincipalsHavingPermissionsInSites
210216

211217
### Request body
212218

213-
| Name | Required | Type | Description |
214-
|--------------------|----------|----------|-------------------------------------------------------------------|
215-
| serverRelativeUrls | yes | string[] | List site collections' server relative url. Maximum size is 500. |
219+
| Name | Required | Type | Description |
220+
|--------------------|----------|----------|------------------------------------------------------------------------------------------------------------|
221+
| serverRelativeUrls | no | string[] | List site collections' server relative url. Maximum size is 500. |
222+
| urls | no | string[] | List site collections' url, both server relative url and absolute url are acceptable. Maximum size is 500. |
223+
224+
When urls is not null, serverRelativeUrls will be disregarded.
216225

217226
### Responses
218227

@@ -228,18 +237,19 @@ POST {adminSiteUrl}/_api/web/GetAddinPrincipalsHavingPermissionsInSites
228237
| title | string | The title of the Add-in. |
229238
| appIdentifier | string | The app identifier. |
230239
| serverRelativeUrl | string | The server relative url of the site collection. |
240+
| absoluteUrl | string | The absolute url of the site collection. |
231241

232242

233243
#### SPErrorWithServerRelativeUrl
234244

235-
| Name | Type | Description |
236-
|-------------------|--------|----------------------------------------------------------|
237-
| serverRelativeUrl | string | The site collection's server relative url. |
238-
| errorMessage | string | The error message why fetch the Add-in principal failed. |
245+
| Name | Type | Description |
246+
|-------------------|--------|------------------------------------------------------------|
247+
| serverRelativeUrl | string | The site collection's server relative url or absolute url. |
248+
| errorMessage | string | The error message why fetch the Add-in principal failed. |
239249

240250
## Uninstall Add-ins
241251

242-
This API will trigger an async job to uninstall the Add-in. If the job triggered successfully, the job id will be returned.
252+
This API will trigger an async job to uninstall the Add-in. If the job triggered successfully, the job id will be returned.
243253

244254
This API needs the app to have Sites.FullControl.All permission.
245255

@@ -257,10 +267,13 @@ POST {adminSiteUrl}/_api/web/UninstallAddins
257267

258268
#### SPUninstallAddinRequest
259269

260-
| Name | Type | Description |
261-
|-------------------|--------|----------------------------------|
262-
| serverRelativeUrl | string | The site's server relative url. |
263-
| appInstanceIds | Guid[] | The instance ids of the Add-ins. |
270+
| Name | Type | Description |
271+
|-------------------|--------|---------------------------------------------------------------------------|
272+
| serverRelativeUrl | string | The site's server relative url. |
273+
| url | string | The site's url, both server relative url and absolute url are acceptable. |
274+
| appInstanceIds | Guid[] | The instance ids of the Add-ins. |
275+
276+
The serverRelativeUrl and url can't be both null. If both serverRelativeUrl and url are provided, the url will be used.
264277

265278
### Responses
266279

@@ -275,6 +288,7 @@ POST {adminSiteUrl}/_api/web/UninstallAddins
275288
|-------------------|--------|---------------------------------|
276289
| appInstanceId | Guid | The instance id of the Add-in. |
277290
| serverRelativeUrl | string | The site's server relative url. |
291+
| absoluteUrl | string | The site's absolute url. |
278292
| uninstallJobId | Guid | The triggered uninstall job id. |
279293

280294
#### SPFailToTriggerUninstallAddinJobResponse
@@ -288,8 +302,8 @@ POST {adminSiteUrl}/_api/web/UninstallAddins
288302

289303
## Get uninstall Add-in job status
290304

291-
Since the uninstall Add-in is an async process, this API will provide the ability to check if the uninstall ends successfully.
292-
If the job ends successfully, then the job will be not found. If the job ends with failure, then it will return the error detail.
305+
Since the uninstall Add-in is an async process, this API will provide the ability to check if the uninstall ends successfully.
306+
If the job ends successfully, then the job will be not found. If the job ends with failure, then it will return the error detail.
293307

294308
This API needs the app to have at least Sites.Read.All permission.
295309

@@ -301,16 +315,20 @@ POST {adminSiteUrl}/_api/web/GetAddinUninstallJobDetail
301315

302316
### Request body
303317

304-
| Name | Required | Type | Description |
305-
|-------------------|----------|--------|---------------------------------|
306-
| jobId | yes | Guid | This uninstall job id. |
307-
| serverRelativeUrl | yes | string | The site's server relative url. |
318+
| Name | Required | Type | Description |
319+
|-------------------|----------|--------|----------------------------------------------------------------------------|
320+
| jobId | yes | Guid | This uninstall job id. |
321+
| serverRelativeUrl | no | string | The site's server relative url. |
322+
| url | no | string | The site's url, both server relative url and absolute url are acceptable. |
323+
324+
The serverRelativeUrl and url can't be both null. If both serverRelativeUrl and url are provided, the url will be used.
308325

309326
### Responses
310327

311328
| Name | Type | Description |
312329
|-------------------|-------------------------------|--------------------------------------------------|
313330
| serverRelativeUrl | string | The site's server relative url. |
331+
| absoluteUrl | string | The site's absolute url. |
314332
| taskStartTime | DateTime | The time when the task starts executing. |
315333
| jobId | Guid | The uninstall job id. |
316334
| siteId | Guid | The site collection id. |

0 commit comments

Comments
 (0)