Manage the environment through public APIs

The Microsoft Fabric REST API provides a service endpoint for the create, read, update, and delete (CRUD) operations of a Fabric item. This article describes the available environment REST APIs and their usage.

Migrate the environment APIs to their stable GA version

APIs with request/response contract update

The preview parameter defaults to True until March 31, 2026, i.e., the system considers the parameter as True if the request is sending without specifying this parameter until the deprecation date. We highly recommend migrating your implementations to the stable version by explicitly set the preview parameter to False as soon as possible.

Using List staging libraries API as an example, which has an update in the API response.

• When sending the request with preview parameter as True

  Sample request:

  GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/environments/{environmentId}/libraries?preview=True
  

  Sample response:

  {
    "customLibraries": {
      "wheelFiles": [
        "samplewheel-0.18.0-py2.py3-none-any.whl"
      ],
      "pyFiles": [
        "samplepython.py"
      ],
      "jarFiles": [
        "samplejar.jar"
      ],
      "rTarFiles": [
        "sampleR.tar.gz"
      ]
    },
    "environmentYml": "name: sample-environment\ndependencies:\n  - fuzzywuzzy==0.0.1\n  - matplotlib==0.0.1"
  }
  

• When sending the request with preview parameter as False

  Sample request:

    GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/environments/{environmentId}/libraries?preview=False
  

  Sample response:

  {
    "libraries": [
      {
        "name": "samplewheel-0.18.0-py2.py3-none-any.whl",
        "libraryType": "Custom"
      },
      {
        "name": "fuzzywuzzy",
        "libraryType": "External",
        "version": "0.0.1"
      }
    ],
    "continuationToken": "null",
    "continuationUri": "null"
  }
  

To-be-deprecated APIs

Belows are a few examples covering the scenarios when managing staging libraries.

• Add the public libraries in your environment

  Previously, you can use Upload staging libraries API to upload the updated YAML file, and now you can use Import external libraries API to import the updated YAML.

• Delete one public library in your environment

  Previously, you can use Upload staging libraries API to upload the updated YAML file, and now you can use Remove external library API to remove it.

• Delete all public library in your environment

  Previously, you can use Delete staging libraries API to delete all the public libraries, and now you can use Remove external library API to remove the public libraries one by one or use Import external libraries to upload an empty YAML file to achieve the same functionalities.

New APIs

APIs without update

To learn more about the environment public APIs, see Item APIs - Environment.

Environment public API use cases

This section demonstrates how to use the APIs to achieve specific scenarios when managing Environment. You can replace the {WORKSPACE_ID} and {ARTIFACT_ID} properties in the following examples with appropriate values.

Create a new environment

To create a new empty environment, use the following API.

• Sample request

  POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments
  
  {
      "displayName": "Environment_1",
      "description": "An environment description"
  }
  

Manage staging libraries

You can use the upload and delete staging libraries APIs to manage the library section in the environment.

Check the published libraries for the environment

Before you add or delete a library, use the Get Published Libraries API to check which libraries are currently effective.

• Sample request

  GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/libraries?preview=False
  

• Sample response

  {
    "libraries": [
      {
        "name": "samplewheel-0.18.0-py2.py3-none-any.whl",
        "libraryType": "Custom"
      },
      {
        "name": "fuzzywuzzy",
        "libraryType": "External",
        "version": "0.0.1"
      }
    ],
    "continuationToken": "null",
    "continuationUri": "null"
  }
  

Import public libraries or upload custom library

You can use Import external libraries and Upload custom library APIs to add new public/custom libraries to your environment. The import external libraries API accepts environment.yml file while the supported file types are .whl, .jar, .tar.gz, .py for upload custom library API.

• Sample requests

  POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/libraries/importExternalLibraries
  

  POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/libraries/samplelibrary.jar
  

Delete the custom library

By specifying the full library file name with the type suffix, you can delete one custom library at a time.

• Sample requests

  DELETE https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/libraries/samplelibrary.jar
  

Manage staging Spark compute

You can use the update staging Spark compute to manage the Spark compute.

Check the published Spark compute for the environment

Before you change the configurations for the environment, use the Get Published Spark Compute API to check what Spark compute configurations are currently effective.

• Sample request

  GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/sparkcompute?preview=False
  

• Sample response

  {
    "instancePool": {
      "name": "MyWorkspacePool",
      "type": "Workspace",
      "id": "78942136-106c-4f3e-80fc-7ff4eae11603"
    },
    "driverCores": 4,
    "driverMemory": "56g",
    "executorCores": 4,
    "executorMemory": "56g",
    "dynamicExecutorAllocation": {
      "enabled": false,
      "minExecutors": 1,
      "maxExecutors": 1
    },
    "sparkProperties": [
      {
        "key": "spark.acls.enable",
        "value": "false"
      }
    ],
    "runtimeVersion": "1.2"
  }
  

Update the compute configurations

You can update the Spark runtime, switch to another pool, refine compute configuration, and add or remove Spark properties through editing the request body of this API.

You can switch the attached pool by specifying the pool name and pool. Specify the pool name as Starter Pool to switch the pool to default settings. To get the full list of the available custom pools of the workspace by REST API, see Custom Pools - List Workspace Custom Pools.

If you want to remove an existing Spark property, specify the value as null with the key that you want to remove.

• Sample request

  PATCH https://api.fabric.microsoft.com/v1/workspaces/f089354e-8366-4e18-aea3-4cb4a3a50b48/environments/707cfd07-cbf1-41da-aad7-dd157ddb8c11/staging/sparkcompute?preview=False
  
  {
    "instancePool": {
      "name": "MyWorkspacePool",
      "type": "Workspace"
    },
    "driverCores": 4,
    "driverMemory": "56g",
    "executorCores": 4,
    "executorMemory": "56g",
    "dynamicExecutorAllocation": {
      "enabled": false,
      "minExecutors": 1,
      "maxExecutors": 1
    },
    "sparkProperties": [
      {
        "key": "spark.acls.enable",
        "value": "false"
      },
      {
        "key": "spark.admin.acls",
        "value": null
      }
    ],
    "runtimeVersion": "1.2"
  }
  

Make the changes effective

Use the following sets of APIs to publish the changes.

Prepare for a publish operation

The environment can accept one publish operation at a time. Before you publish your environment, validate the status of the environment and have a final review of the staging changes. After the environment is published successfully, all configurations in the staging state become effective.

• Step 1: Get the metadata of the environment.

  GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/
  

  In the response body, you can clearly tell the state of the environment. Make sure that no publish operation is ongoing before you move to the next step.

• Step 2: Get the staging libraries/Spark compute to have a final review.

  GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/libraries?preview=False
  
  GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/sparkcompute?preview=False
  

Trigger the publish operation of the environment

The changes that you made for the staging libraries and Spark compute are cached, but they require publishing to become effective. Use the next example to trigger the publish operation. Response is following long running operations (LRO) pattern and HTTP response code 202 may be returned.

• Sample request

  POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/publish?preview=False
  

• Sample response

  Location: https://api.fabric.microsoft.com/v1/operations/abcdef00-9d7e-469a-abf1-fca847a0ea69
  x-ms-operation-id: abcdef00-9d7e-469a-abf1-fca847a0ea69
  Retry-After: 120  
  

During the publish operation, you can also call the following API to cancel it.

• Sample request

  POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/cancelPublish
  

Related content

• Create, configure, and use an environment in Fabric
• Item APIs - Environment