## PowerBI Report Listing and Embedding API: Technical Documentation

### Introduction

This document outlines the technical requirements for an API that retrieves information about Power BI reports, including embedded URLs and applied Row Level Security (RLS) rules. It includes both a GET endpoint for listing reports and a POST endpoint for generating specific report embed URLs.

### API Endpoints

1. **GET /reports**: This endpoint retrieves a list of all accessible Power BI reports within the authorized user's workspace or organization.
2. **POST /reports/embed**: This endpoint generates an embedded URL for a specific Power BI report, considering the provided report ID and RLS information.

### Data Model

#### GET /reports Response

The response of the GET endpoint will be a JSON object containing the following properties for each report:

* **reportId**: Unique identifier for the Power BI report (string)
* **name**: Display name of the report (string)
* **webUrl**: Public URL of the report in the Power BI service (string)
* **embedUrl**: Base URL for generating embedded URLs (string)
* **rlss**: An array of RLS rule summaries for the report. Each summary will include:
* **table**: Name of the table affected by the RLS rule (string)
* **field**: Name of the field used in the RLS rule (string)
* **operator**: The comparison operator used in the rule (string, e.g., "=", "<", "IN")
* **values**: An array of allowed values for the field based on the rule (string or array of strings)

#### POST /reports/embed Request

The POST request body will contain the following JSON object:

* **reportId**: Unique identifier of the Power BI report (string)
* **rlss**: An array of RLS filters to apply to the embedded report. Each filter will include:
* **table**: Name of the table to apply the filter to (string)
* **field**: Name of the field to filter (string)
* **operator**: The comparison operator used in the filter (string, e.g., "=", "<", "IN")
* **values**: An array of allowed values for the field based on the filter (string or array of strings)

#### POST /reports/embed Response

The response of the POST endpoint will be a JSON object containing the following property:

* **embedUrl**: Generated URL for embedding the report with the specified RLS filters (string)

### Authentication and Authorization

* Both endpoints require valid authorization to access Power BI resources. Use OAuth2.0 with Azure Active Directory (AAD) to authenticate users and secure API access.
* The required scopes for the GET endpoint are "Reports.Read.All" or "Report.Read.All".
* The required scopes for the POST endpoint are "Reports.Read.All" and "Reports.ReadWrite.All".

### Error Handling

* The API should return appropriate HTTP status codes and error messages for various scenarios, such as unauthorized access, invalid requests, and unavailable resources.

### Additional Considerations

* Implement Authentication mechanisms like Static Bearer Token to prevent API abuse.
* Implement throttling mechanisms to prevent API abuse.
* Implement caching mechanisms to optimize performance for frequently accessed reports.

### Implementation Technologies

* • Choose a reliable web framework and programming language suitable for building RESTful APIs (e.g., ASP.NET Core, Node.js). If one doesn’t have these then Low-Code No-Code (LCNC) Platforms like Power Automate can be used.
* Utilize Power BI REST APIs and Azure Active Directory libraries for authentication and accessing Power BI resources.
* Leverage JSON for data serialization and deserialization.

### Documentation and Testing

* Provide comprehensive API documentation, including request and response formats, error codes, and usage examples.
* Implement unit and integration tests to ensure API functionality and reliability.