The Power BI APIs are evolving! Because of the importance of datasets, the initial set of APIs was centered around dataset manipulation. Later on, the team added group,
dashboard, and report APIs, with more APIs coming in the future. In this section, you’ll learn about the capabilities of the existing methods.
NOTE Currently, some REST APIs are in preview, and their method signatures show you this, such as “beta” in the URL: https://api.powerbi.com/beta/myorg/dashboards. Remember to update your code when the beta methods move to production. For example, when the “Get All Dashboards” method is production ready, its method signature needs to be changed to https://api.powerbi.com/v1.0/myorg/dashboards.
Understanding the verbs
As I mentioned, the Power BI APIs are based on a programming specification for method invocation over HTTP, called Representational State Transfer (or REST for short).
Because the same API can serve different purposes, REST supports a set of HTTP verbs to indicate the purpose of the method invocation. For example, to get the list of existing datasets, you’ll use the GET verb. Power BI supports the most common HTTP verbs, as shown in Table 11.2.
Table 11.2 Power BI supports four HTTP verbs.
Verb Operation Success Response Codes Error Response Codes
GET Read 200 (OK) 404 (Not Found) or 400 (Bad Request).
POST Create 201 (Created) 404 (Not Found), 409 (Conflict) if resource
already exists PUT Update 200 (OK) (or 204 if not returning any content in
response body) 404 (Not Found) if ID is not found
DELETE Delete 200 (OK) 404 (Not Found) if ID is not found
The HTTP GET method is used to retrieve a representation of a resource, such as a dataset collection. When executed successfully, GET returns the JSON representation in the
response body. POST is used to create a new resource, such as a new dataset. Upon
successful completion, it returns the HTTP status 201 and a Location header with a link to
the newly-created resource.
You typically use the PUT verb to update an existing resource by using the unique
identifier of the resource. Upon a successful update, you’ll get a response code of 200 (or 204 if the API doesn’t return any content in the response body). Finally, given an
identifier, DELETE removes the specified resource, such as a given row in a dataset table.
Understanding the dataset methods
The dataset-related methods are centered around the manipulation of datasets and tables, as shown in Table 11.3. Using the Power BI Rest API’s, you can programmatically create new datasets, and you can add or remove rows to and from the tables in those datasets.
Table 11.3 This table shows the dataset-related methods.
Purpose Verb Method Signature Parameters
List all
datasets GET https://api.powerbi.com/v1.0/myorg/datasets Create a
dataset POST https://api.powerbi.com/v1.0/myorg/datasets?
defaultRetentionPolicy=None
defaultRetentionPolicy (None, basicFIFO)
List all tables GET https://api.powerbi.com/v1.0/myorg/datasets/id/tables id (the dataset identifier) Change table PUT https://api.powerbi.com/v1.0/myorg/datasets/id/tables/TableName id (the dataset identifier),
TableName Add table
rows POST https://api.powerbi.com/v1.0/myorg/datasets/id/tables/TableName/rows id (the dataset identifier), TableName
Remove all
rows DELETE https://api.powerbi.com/v1.0/myorg/datasets/id/tables/TableName/rows id (the dataset identifier), TableName
As you can see, the verb indicates the intended action. For example, if I use the GET verb when I call the dataset API, I’ll get a list of all the datasets, exactly as they’re listed in the Power BI Service navigation bar under My Workspace. If I call the same API with a POST verb, I instruct Power BI to create a new dataset. In the latter case, I can specify an optional defaultRetentionPolicy parameter. This controls the store capacity of the dataset.
The retention policy becomes important when you start adding rows to the dataset, such as to supply data to a real-time dashboard. By default, the dataset will accumulate all the rows. However, if you specify defaultRetentionPolicy=basicFIFO, the dataset will store up to 200,000 rows. Once this limit is reached, Power BI will start purging old data as new data comes in (see Figure 11.2).
Figure 11.2 The basic FIFO dataset policy stores up to 200,000 rows and removes old data as new data flows in.
Understanding the dashboard methods
Currently in preview, the dashboard methods allow you to retrieve dashboards and tiles.
This is useful if you need to embed a dashboard tile on a custom application, as I’ll cover in Chapter 12. Table 11.4 shows you the dashboard methods.
Table 11.4 This table shows the dashboard-related methods.
Purpose Verb Method Signature Parameters List all
dashboards GET https://api.powerbi.com/beta/myorg/dashboards
List tiles GET https://api.powerbi.com/beta/myorg/dashboards/<id>/tiles id (dashboard identifier)
Currently, there are only two methods. The first method returns a list of dashboards as they appear in the Power BI portal’s navigation bar. Every dashboard element in the response body has a GUID identifier, name, and an isReadOnly property that indicates whether the dashboard is read-only, such as when it’s shared with you by someone else, and you’re given read-only access. The “List Tiles” method takes the dashboard identifier, and returns a collection of the dashboard tiles. Here’s a sample JSON format that describes the “This Year’s Sales” tile of the Retail Analysis Sample dashboard:
{
“id”: “b2e4ef32-79f5-49b3-94bc-2d228cb97703”,
“title”: “This Year’s Sales”,
“subTitle”: “by Chain”,
“embedUrl”: “https://app.powerbi.com/embed?dashboardId=<dashboard id>&tileId=b2e4ef32-79f5-49b3-94bc- 2d228cb97703”
}
From a content embedding standpoint, the most important element is embedUrl, because your application needs it to reference the tile.
Understanding the report methods
Currently in preview, the report API allows you to retrieve reports. This is useful if you need to embed a report in a custom application, as I’ll cover in Chapter 12. Table 11.5 shows the “List All Reports” method that allows you to programmatically retrieve your reports.
Table 11.5 This table shows the dashboard-related methods.
Purpose Verb Method Signature Parameters
List all reports GET https://api.powerbi.com/beta/myorg/reports
The “List All Reports” method returns a list of reports as they appear in the navigation bar.
Every report element in the response body has a GUID-based identifier (id), name,
webUrl, and embedUrl. The webUrl link navigates to the report in Power BI Service. The embedUrl link is used to embed the report in a custom application. Here’s a sample JSON format that describes the Retail Analysis Sample report that you implemented in Chapter 3.
{
“id”:“22454c20-dde4-46bc-9d72-5a6ea969339e”,
“name”:“Retail Analysis Sample”,
“webUrl”:“https://app.powerbi.com/reports/22454c20-dde4-46bc-9d72-5a6ea969339e”,
“embedUrl”:“https://app.powerbi.com/reportEmbed?reportId=22454c20-dde4-46bc-9d72-5a6ea969339e”
}
Understanding the group methods
As you probably know by now, a user can access other workspaces. Therefore, to present
the user with all the objects he has access to, a custom app must enumerate not only the user’s My Workspace but also all other groups he’s a member of. Currently, Power BI defines only one group method (see Table 11.6).
Table 11.6 This table shows the List all Groups method.
Purpose Verb Method Signature Parameters
List all groups GET https://api.powerbi.com/v1.0/myorg/groups
This method returns all groups the sign-in user belongs to. Each group element has the id and name properties. Here’s an example that returns the Sales Department and Finance groups that I belong to:
“value”: [ {
“id”: “42e3a472-2855-4a78-aec7-387d2e8722ae”,
“name”: “Sales Department”
}, {
“id”: “e6e4e5ab-2644-4115-96e0-51baa89df249”,
“name”: “Finance”
}
TIP What if you want to retrieve objects from another workspace that you’re a part of through your group
membership, such as to list the datasets from the Finance workspace, or to create a new dataset that’s shared by all the members of a group? Fortunately, the dataset, dashboard, and report methods support specifying a group. For example, to list all of the dataset for a specific group, you can invoke
https://api.PowerBI.com/v1.0/myorg/groups/{group_id}/datasets, where group_id is the group unique identifier that you can obtain by calling the “List all groups” method. As it stands, the developer’s console doesn’t allow you to change the method signature, so you can’t use the group syntax in the Power BI Developer Center, but you can use this syntax in your applications.
Understanding the import methods
The import APIs lets you programmatically upload a Power BI Desktop file (*.pbix) or an Excel file to a user’s workspace. This could be useful if you want to automate the
deployment process of uploading datasets and reports but remember that organizational content packs might be an easier and more flexible option to distribute content to many users. Table 11.7 shows the method signatures.
Table 11.7 This table shows the Import File method signatures.
Purpose Verb Method Signature Parameters
Import File POST https://api.powerbi.com/beta/myorg/imports datasetDisplayName nameConflict GET https://api.powerbi.com/beta/myorg/imports/importID
To import a file, you must create a “POST” request that takes two parameters:
datasetDisplayName – The name of the resulting dataset after the import is complete.
nameConflict – Specifies the behavior if the name of that dataset already exists. Specify
“Abort” to fail the method, “Overwrite” to replace existing datasets and reports, and
“Ignore” (default) to ignore the conflicting names.
The request must conform to the multipart/form-data
specification (http://bit.ly/1OOwF4l). Figure 11.3 shows a sample request:
Figure 11.3 A sample request body for importing a file.
The Content-Disposition header specifies “form-data” and the source file name. The Content-Type header is set to “application/octet-stream”. Next, the request body includes the entire contents of the file, byte for byte. Don’t base-64 encode it, just serialize it as a stream.
The actual import operation isn’t blocking and executes asynchronously. When you invoke the POST signature, you’ll get back a 202 accepted response. The response body will include a GUID identifier for the import task, such as:
{“id” : “12e3a412-2855-4a78-aec7-387d2e1234ae”}
You can use this identifier to check the status of the import task by using the GET verb signature and passing it the importID identifier. You’ll get back a JSON response, such as the one shown in Figure 11.4.
Figure 11.4 The response of the GET verb invocation shows the status of the operation.
Your code can inspect the importState property to determine if the import task has completed.