Edit

Develop with the REST APIs for Reporting Services

  • Article

Applies to: ✅ SQL Server Reporting Services (2017 and later) ❌ Power BI Report Server

Microsoft SQL Server 2017 Reporting Services supports Representational State Transfer (REST) APIs. The REST APIs are service endpoints that support a set of HTTP operations (methods), which provide create, retrieve, update, or delete access for resources within a report server.

The REST API provides programmatic access to the objects in a SQL Server 2017 Reporting Services report server catalog. Examples of objects are folders, reports, KPIs, data sources, datasets, refresh plans, subscriptions, and more. Using the REST API, you can, for example, navigate the folder hierarchy, discover the contents of a folder, or download a report definition. You can also create, update, and delete objects. Examples of working with objects include uploading a report, executing a refresh plan, deleting a folder, and so on.

Note

If you're interested in viewing or deleting personal data, please review Microsoft's guidance in the Windows Data Subject Requests for the GDPR site. If you're looking for general information about GDPR, see the GDPR section of the Service Trust portal.

Components of a REST API request/response

A REST API request/response pair can be separated into five components:

  • The request URI, which consists of: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Although the request URI is included in the request message header, we call it out separately here because most languages or frameworks require you to pass it separately from the request message.

    • URI scheme: Indicates the protocol used to transmit the request. For example, http or https.
    • URI host: Specifies the domain name or IP address of the server where the REST service endpoint is hosted, such as myserver.contoso.com.
    • Resource path: Specifies the resource or resource collection, which might include multiple segments used by the service in determining the selection of those resources. For example: CatalogItems(01234567-89ab-cdef-0123-456789abcdef)/Properties can be used to get the specified properties for the CatalogItem.
    • Query string (optional): Provides more simple parameters, such as the API version or resource selection criteria.

  • HTTP request message header fields:

    • A required HTTP method (also known as an operation or verb), which tells the service what type of operation you're requesting. Reporting Services REST APIs support DELETE, GET, HEAD, PUT, POST, and PATCH methods.
    • Optional extra header fields, as required by the specified URI and HTTP method.

  • Optional HTTP request message body fields, to support the URI and HTTP operation. For example, POST operations contain MIME-encoded objects that are passed as complex parameters. For POST or PUT operations, the MIME-encoding type for the body should be specified in the Content-type request header as well. Some services require you to use a specific MIME type, such as application/json.

  • HTTP response message header fields:

    • An HTTP status code, ranging from 2xx success codes to 4xx or 5xx error codes. Alternatively, a service-defined status code might be returned, as indicated in the API documentation.
    • Optional extra header fields, as required to support the request's response, such as a Content-type response header.

  • Optional HTTP response message body fields:

    • MIME-encoded response objects are returned in the HTTP response body, such as a response from a GET method that is returning data. Typically, these objects are returned in a structured format such as JSON or XML, as indicated by the Content-type response header.

API documentation

A modern REST API calls for modern API documentation. The REST API is built on the OpenAPI specification (also called the swagger specification) and documentation is available on SwaggerHub. Beyond documenting the API, SwaggerHub helps generate a client library in the language of choice - JavaScript, TypeScript, C#, Java, Python, Ruby, and more.

Test API calls

A tool for testing HTTP request/response messages is Fiddler. Fiddler is a free web debugging proxy that can intercept your REST requests, making it easy to diagnose the HTTP request/ response messages.

Next steps

Review the available APIs over on SwaggerHub.

Samples are available on GitHub. The sample includes an HTML5 app built on TypeScript, React, and Webpack along with a PowerShell example.

More questions? Try asking the Reporting Services forum