Microsoft Fabric REST API

Microsoft Fabric REST API is a tool, that can help you automate tasks in Fabric. By saying automate, I mean you can use it to automatically manage Fabric items, run notebooks, setup workspaces etc. The full API documentation can be found from this URL.

Getting Started with Fabric APIs

To use the Fabric API, you need a Microsoft Entra authentication token, as Fabric does not support API keys or SAS tokens for REST API authentication. Currently (as of 7/9/2024), the Entra token can only be acquired through interactive authentication. You will also need an Entra Client ID (app registration) with localhost redirect uri.

Permissions and Scopes

To work with Microsoft Fabric REST APIs, you need to get a Microsoft Entra token with delegated scopes. The API documentation helps to demystify different scopes really well and you can look from there what scopes are required for which actions. Permission scopes can be split into two main categories:

Generic = Easier to use to, but bit insecure (wider permissions)
Specific = More secure, but needs to defined specifically for each actions.

There are four types of generic scopes available:

Item.Reshare.All: Calling application is allowed to reshare all Fabric items.
Item.Read.All: Calling application is allowed to read all Fabric items.
Item.ReadWrite.All: Calling application is allowed to read and write all Fabric items.
Item.Execute.All: Calling application is allowed to execute on all Fabric items.

Specific scopes are all in format of <itemType>.Read.All or <itemType>.ReadWrite.All, for example: Notebook.ReadWrite.All.

What are Fabric Items?

Before we start, we need to know few things about the API. Fabric API is split into two “sections”: Fabric Items and Core functionalities. Fabric item is basically an environment, notebook or a Lakehouse. It is a manageable resource inside Fabric. Fabric item API’s are in format of https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/{itemtype}/{id}. For example https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/dataPipelines/{dataPipelineId}.
You can run CRUD methods against all these items through API.

Core and Workload APIs

Core functionalities are things like running a notebook or setting up a GIT connection. Core functionality is an action, but this section also holds the Workspace management (get,list,delete and create). Core function URLs varies a bit more than Fabric Item URLs. For example to get list of available Fabric capacities, we could use GET https://api.fabric.microsoft.com/v1/capacities method. For running a notebook we should use POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{itemId}/jobs/instances?jobType={jobType} method.

Using REST API From C# Console App

In next sample code I will show you how to acquire authentication token with notebook execute scope and how to run notebook. The authentication is implemented by using this sample code from GitHub. I’m using MSAL.NET here to acquire the auth token.

string ClientId = "(App registration with localhost redirect uri)";
string Authority = "https://login.microsoftonline.com/(tenant id)/";

// We can use multiple scopes, but now lets just define notebook execute permission.
string[] scopes = ["https://api.fabric.microsoft.com/Notebook.Execute.All"];

PublicClientApplicationBuilder PublicClientAppBuilder =
        PublicClientApplicationBuilder.Create(ClientId)
        .WithAuthority(Authority)
        .WithDefaultRedirectUri();

IPublicClientApplication PublicClientApplication = PublicClientAppBuilder.Build();

try
{
    // We need to use interactive, because Fabric does not support any other auth method currently.
    AuthenticationResult result = await PublicClientApplication
        .AcquireTokenInteractive(scopes) 
        .ExecuteAsync();

    if (!string.IsNullOrEmpty(result.AccessToken))
    {
        var loginExpires = result.ExpiresOn;
        var accessToken = result.AccessToken; // Store the access token for later use.
    }
    else
    {
        throw new Exception("Login failed. Check application ID.");
    }
}
catch (Exception ex)
{
    _logger.LogError(ex, "Failed to login.");
}

I want to raise up few things from this sample code. I’m using Notebook.Execute.All scope in this sample, which is a generic type of scope. This scope is required to run any notebooks in Fabric. Another thing is, that we need to use AcquireTokenInteractive method, as Fabric does not currently support any other authentication methods (this will change). I also cannot use Azure.Identity NuGet package to do the authentication, because it does not support multiple scopes.

Running Notebook

After acquiring token running the notebook is quite simple. There is only one undocumented part of the URL, that can be a real pain in the ass and that is jobType. If you look sample codes from Microsoft documentation, you will notice that they are all using DefaultJob jobType parameter. That simply does not work. Also the documentation does not have any mentions about job types and what values could be used. Luckily I was able to find the job type (RunNotebook) for notebooks from Microsoft forums.

  // _clientFactory is implementation of IHttpClientFactory
  var client = _clientFactory.CreateClient();
  // place workspaceid (guid) and notebookid (guid) into url.
  var url = $"https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{notebookId}/jobs/instances?jobType=RunNotebook";
  client.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken}");

  var response = await client.PostAsync(url, null);
  if (response.IsSuccessStatusCode)
  {
      jobLocation = response.Headers.Location;
      // we can use jobLocation URL to query the status of notebook run.
  }

Conclusion

Microsoft Fabric REST API will be a great tool to automate fabric item management. However currently it lacks the authentication support for managed identities etc. so it is only suitable for manual scripting. API will support other auth methods in near future, so this is subject to change in a short matter.