Skip to content

Commit

Permalink
API design: Self-service: Install Apple App Store apps on macOS (#22102)
Browse files Browse the repository at this point in the history 
API design for:
- #19620
  • Loading branch information
@marko-lisica
marko-lisica authored Oct 1, 2024
1 parent beec753 commit c545495
Show file tree
Hide file tree
Showing 3 changed files with 228 additions and 145 deletions.
4 changes: 3 additions & 1 deletion docs/Configuration/yaml-files.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -354,7 +354,9 @@ software:

- `app_store_id` is the ID of the Apple App Store app. You can find this at the end of the app's App Store URL. For example, "Bear - Markdown Notes" URL is "https://apps.apple.com/us/app/bear-markdown-notes/id1016366447" and the `app_store_id` is `1016366447`.

> Make sure to include only the ID itself, and not the `id` prefix shown in the URL. The ID must be wrapped in quotes as shown in the example so that it is processed as a string.
> Make sure to include only the ID itself, and not the `id` prefix shown in the URL. The ID must be wrapped in quotes as shown in the example so that it is processed as a string.

`self_service` only applies to macOS, and is ignored for other platforms. For example, if the app is supported on macOS, iOS, and iPadOS, and `self_service` is set to `true`, it will be self-service on macOS workstations but not iPhones or iPads.

##### Separate file

Expand Down
191 changes: 190 additions & 1 deletion docs/Contributing/API-for-contributors.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -541,6 +541,10 @@ The MDM endpoints exist to support the related command-line interface sub-comman
- [Renew VPP token](#renew-vpp-token)
- [Delete VPP token](#delete-vpp-token)
- [Batch-apply MDM custom settings](#batch-apply-mdm-custom-settings)
- [Batch-apply packages](#batch-apply-packages)
- [Batch-apply App Store apps](#batch-apply-app-store-apps)
- [Get token to download package](#get-token-to-download-package)
- [Download package using a token](#download-package-using-a-token)
- [Initiate SSO during DEP enrollment](#initiate-sso-during-dep-enrollment)
- [Complete SSO during DEP enrollment](#complete-sso-during-dep-enrollment)
- [Over the air enrollment](#over-the-air-enrollment)
Expand Down Expand Up @@ -1743,7 +1747,7 @@ If the `name` is not already associated with an existing team, this API route cr
| scripts | list | body | A list of script files to add to this team so they can be executed at a later time. |
| software | object | body | The team's software that will be available for install. |
| software.packages | list | body | An array of objects. Each object consists of:`url`- URL to the software package (PKG, MSI, EXE or DEB),`install_script` - command that Fleet runs to install software, `pre_install_query` - condition query that determines if the install will proceed, `post_install_script` - script that runs after software install, and `self_service` boolean. |
| software.app_store_apps | list | body | An array objects. Each object consists of `app_store_id` - ID of the App Store app formatted as a string (in quotes) rather than a number. |
| software.app_store_apps | list | body | An array of objects. Each object consists of `app_store_id` - ID of the App Store app and `self_service` boolean. |
| mdm.macos_settings.enable_disk_encryption | bool | body | Whether disk encryption should be enabled for hosts that belong to this team. |
| force | bool | query | Force apply the spec even if there are (ignorable) validation errors. Those are unknown keys and agent options-related validations. |
| dry_run | bool | query | Validate the provided JSON for unknown keys and invalid value types and return any validation errors, but do not apply the changes. |
Expand Down Expand Up @@ -1836,6 +1840,7 @@ If the `name` is not already associated with an existing team, this API route cr
"app_store_apps": [
{
"app_store_id": "12464567",
"self_service": true
}
]
}
Expand Down Expand Up @@ -3376,3 +3381,187 @@ Run a live script and get results back (5 minute timeout). Live scripts only run
"exit_code": 0
}
```
## Software

### Batch-apply software

_Available in Fleet Premium._

`POST /api/v1/fleet/software/batch`

This endpoint is asynchronous, meaning it will start a background process to download and apply the software and return a `request_uuid` in the JSON response that can be used to query the status of the batch-apply (using the `GET /api/v1/fleet/software/batch/:request_uuid` endpoint defined below).

#### Parameters

| Name | Type | In | Description |
| --------- | ------ | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| team_name | string | query | The name of the team to add the software package to. Ommitting these parameters will add software to 'No Team'. |
| dry_run | bool | query | If `true`, will validate the provided software packages and return any validation errors, but will not apply the changes. |
| software | object | body | The team's software that will be available for install. |
| software.packages | list | body | An array of objects. Each object consists of:`url`- URL to the software package (PKG, MSI, EXE or DEB),`install_script` - command that Fleet runs to install software, `pre_install_query` - condition query that determines if the install will proceed, `post_install_script` - script that runs after software install, and `uninstall_script` - command that Fleet runs to uninstall software. |

#### Example

`POST /api/v1/fleet/software/batch`

##### Default response

`Status: 200`
```json
{
"request_uuid": "ec23c7b6-c336-4109-b89d-6afd859659b4",
}
```

### Get status of software batch-apply request

_Available in Fleet Premium._

`GET /api/v1/fleet/software/batch/:request_uuid`

This endpoint allows querying the status of a batch-apply software request (`POST /api/v1/fleet/software/batch`).
Returns `"status"` field that can be one of `"processing"`, `"complete"` or `"failed"`.
If `"status"` is `"completed"` then the `"packages"` field contains the applied packages.
If `"status"` is `"processing"` then the operation is ongoing and the request should be retried.
If `"status"` is `"failed"` then the `"message"` field contains the error message.

#### Parameters

| Name | Type | In | Description |
| ------------ | ------ | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| request_uuid | string | query | The request_uuid returned by the `POST /api/v1/fleet/software/batch` endpoint. |
| team_name | string | query | The name of the team to add the software package to. Ommitting these parameters will add software to 'No Team'. |
| dry_run | bool | query | If `true`, will validate the provided software packages and return any validation errors, but will not apply the changes. |

##### Default responses

`Status: 200`
```json
{
"status": "processing",
"message": "",
"packages": null
}
```

`Status: 200`
```json
{
"status": "completed",
"message": "",
"packages": [
{
"team_id": 1,
"title_id": 2751,
"url": "https://ftp.mozilla.org/pub/firefox/releases/129.0.2/win64/en-US/Firefox%20Setup%20129.0.2.msi"
}
]
}
```

`Status: 200`
```json
{
"status": "failed",
"message": "validation failed: software.url Couldn't edit software. URL (\"https://foobar.does.not.exist.com\") returned \"Not Found\". Please make sure that URLs are reachable from your Fleet server.",
"packages": null
}
```

### Batch-apply App Store apps

_Available in Fleet Premium._

`POST /api/latest/fleet/software/app_store_apps/batch`

#### Parameters

| Name | Type | In | Description |
| --------- | ------ | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| team_name | string | query | The name of the team to add the software package to. Ommitting this parameter will add software to "No team". |
| dry_run | bool | query | If `true`, will validate the provided VPP apps and return any validation errors, but will not apply the changes. |
| app_store_apps | list | body | An array of objects. Each object contains `app_store_id` and `self_service`. |
| app_store_apps.app_store_id | string | body | ID of the App Store app. |
| app_store_apps.self_service | boolean | body | Whether the VPP app is "Self-service" or not. |

#### Example

`POST /api/latest/fleet/software/app_store_apps/batch`
```json
{
"team_name": "Foobar",
"app_store_apps": {
{
"app_store_id": "597799333",
"self_service": false,
},
{
"app_store_id": "497799835",
"self_service": true,
}
}
}
```

##### Default response

`Status: 204`

### Get token to download package

_Available in Fleet Premium._

`POST /api/v1/fleet/software/titles/:software_title_id/package/token?alt=media`

The returned token is a one-time use token that expires after 10 minutes.

#### Parameters

| Name | Type | In | Description |
|-------------------|---------|-------|------------------------------------------------------------------|
| software_title_id | integer | path | **Required**. The ID of the software title for software package. |
| team_id | integer | query | **Required**. The team ID containing the software package. |
| alt | integer | query | **Required**. Must be specified and set to "media". |

#### Example

`POST /api/v1/fleet/software/titles/123/package/token?alt=media&team_id=2`

##### Default response

`Status: 200`

```json
{
"token": "e905e33e-07fe-4f82-889c-4848ed7eecb7"
}
```

### Download package using a token

_Available in Fleet Premium._

`GET /api/v1/fleet/software/titles/:software_title_id/package/token/:token?alt=media`

#### Parameters

| Name | Type | In | Description |
|-------------------|---------|------|--------------------------------------------------------------------------|
| software_title_id | integer | path | **Required**. The ID of the software title to download software package. |
| token | string | path | **Required**. The token to download the software package. |

#### Example

`GET /api/v1/fleet/software/titles/123/package/token/e905e33e-07fe-4f82-889c-4848ed7eecb7`

##### Default response

`Status: 200`

```http
Status: 200
Content-Type: application/octet-stream
Content-Disposition: attachment
Content-Length: <length>
Body: <blob>
```
Loading

0 comments on commit c545495

Please sign in to comment.