REST API explained with examples for Power BI developers

Introduction?

If you've ever had to deal with web services, it's highly likely you've come across the term REST API. APIs (Application Programming Interfaces) are like the pipelines for different software applications to communicate and share data with each other. When talking about web services, we often refer to REST APIs - a standard style of API design that is widely adopted due to its simplicity and scalability. In this article, I will do my best to make you familiar with REST APIs, taking our time to walk you through all its essentials. Examples will be drawn from Azure and Power BI, two popular services by Microsoft that leverage REST APIs extensively. I’ve chosen them because I use them in my everyday tasks. Leveraging those tools saves me many hours of manual work and lots of component I build are reusable for future project. So, good understanding of REST APIs is a ticket to the world of easier and more efficient job!?

What is an API??

Before we deep dive into REST APIs, we need to thoroughly understand what API is. This acronym stands for Application Programming Interface, can be thought of as a set of rules that allows different software applications to communicate with each other. Essentially, it's like a menu in a restaurant. The menu provides a list of dishes you can order, along with a description of each dish. When you specify what menu items you want, the kitchen does the work and provides you with some finished dishes. You don't know exactly how the kitchen prepares that food, and you don't really need to.?

Similarly, an API lists a bunch of operations that a programmer can use, along with a description of what each operation does. The programmer doesn't need to understand how the operations are implemented - they just need to know what it does and what they need to provide to use it.?

For instance, when you use an application on your mobile phone, the app connects to the Internet and sends data to a server. The server then retrieves that data, interprets it, performs the necessary actions, and sends it back to your phone. The application then interprets that data and presents you with the information you wanted in a readable way. This is what an API is all about.?

Why Do We Need APIs??

APIs, whether they're SOAP, REST, or any other type, are crucial in enabling software applications to interact, exchange data, and perform tasks seamlessly. They act as an intermediary between different software systems, allowing them to communicate and understand each other.?

For instance, consider a travel booking website. This website might use APIs to interact with airline companies' systems, hotel systems, and other travel service systems. When you search for a flight on the booking website, it sends a request to the airline's system via its API, asking for information on available flights. The airline's system sends back a response, which the booking website then presents to you. This process happens in real time and is made possible by APIs.?

In summary, APIs enable different software systems to interact in a standardized way, making it possible to integrate different systems and create complex, feature-rich applications. They hide the complexity of these systems, allowing developers to use their functionality without needing to understand all the details of how they work.?

SOAP API?

In previous paragraph I mentioned SOAP API, let’s explain what it is. Before the introduction of REST APIs, there was another type of web service communication protocol known as SOAP (Simple Object Access Protocol). SOAP is a standard protocol defined by the World Wide Web Consortium (W3C) that allows for the exchange of structured information in web services using XML. SOAP can operate over any protocol, such as HTTP, SMTP or even FTP, and is highly extensible and versatile, which allows it to be utilized in a wide range of applications.?

However, SOAP can be quite complex to use, and its heavy use of XML can lead to large, verbose messages. This has led many developers to adopt the simpler, more lightweight REST architecture for their APIs.?

Here are a few places you might still encounter SOAP APIs:?

• Financial Services: Many banking and financial systems use SOAP APIs due to the high level of security they provide. SOAP supports WS-Security, which provides a suite of security features such as integrity, confidentiality, and authentication.?
• Telecommunications: Many telecom systems, especially older ones, use SOAP APIs for internal communication and system integration.?
• Healthcare: Healthcare systems often require the reliability and extensibility provided by SOAP APIs, especially when dealing with patient data. Also, SOAP supports HL7 over HTTP, a protocol widely used in healthcare information systems.?
• Shipping and Logistics: Companies like UPS and FedEx offer SOAP APIs for their services, which allow developers to access tracking information, create shipping labels, and schedule pickups.?
• Enterprise Software: Large enterprise software packages, such as CRMs and ERPs, often use SOAP APIs for integration purposes. Examples include SAP and Microsoft Dynamics.?

While the trend in recent years has been towards RESTful APIs due to their simplicity and ease of use, SOAP remains a viable and important technology, especially in sectors where its particular strengths are required. As always, the choice between SOAP and REST (or indeed other technologies) will depend on the specific requirements of the project at hand.?

What is a REST API??

REST, which stands for Representational State Transfer, is a set of principles for designing networked applications. APIs following these principles are referred to as RESTful APIs or simply REST APIs. Essentially, a REST API provides a structured way for applications to interact with each other over the internet.?

To simplify this, imagine you want to request a movie from a video streaming service like Netflix. You choose a movie, and Netflix's server gets the information about the movie, such as its title, description, and the actual video file. This process involves sending requests from the Netflix application on your device to the Netflix server, which then sends back the necessary data. This communication happens through an API - in this case, a REST API.?

Key Concepts in REST API?

Now, let's understand some key REST concepts.?

Resources?

In REST APIs, a "resource" refers to any object that can be accessed. For instance, in Azure, a virtual machine or a database could be considered resources. Similarly, in Power BI, a report or dashboard can be seen as a resource.?

Endpoints?

Each resource is identified by a specific URL, known as an "endpoint". For instance, in Power BI, an endpoint could look something like this: https://api.powerbi.com/v1.0/myorg/reports/{reportId}, where {reportId} is replaced with the actual ID of a report. This endpoint allows you to interact with the specific report identified by the {reportId}.?

What is HTTP?

HTTP, which stands for Hypertext Transfer Protocol, is the foundational protocol used for transferring data over the internet. It's essentially the language that web browsers (like Google Chrome or Firefox) use to communicate with web servers, which host websites and other data.?

When you type a URL into your web browser, it sends an HTTP request to the web server that hosts the corresponding website. The server then sends back an HTTP response, containing the content of the website which your browser then displays.?

HTTP is a crucial part of the web as we know it, allowing for the communication that forms the basis of web browsing. It's a stateless protocol, which means each request is treated independently and doesn't retain information from previous requests. This simplicity is one of the reasons for the widespread adoption of HTTP.?

HTTP Methods?

When interacting with a REST API, we use standard HTTP methods. These methods define what action we intend to perform:?

• GET: Retrieve data from a specific resource.?
• POST: Send data to a server to create a new resource.?
• PUT: Update a specific resource with new data.?
• DELETE: Remove a specific resource.?

For example, in Power BI, you could use a GET request to list of reports in a given workspace, a POST request to refresh dataset, a PUT request to update a file to Azure Storage Account, or a DELETE request to remove a resource in Azure subscription.?

Status Codes?

HTTP status codes are three-digit numbers returned by servers to indicate the status of a web element or to communicate how a browser should proceed. These codes are divided into five classes, each of which signifies a category of response.?

• 1xx - Informational: This class of status code indicates a provisional response. These codes are rarely seen in actual usage. Example: 100 Continue?
• 2xx - Successful: These codes indicate that the client's request was successfully received, understood, and accepted. Example: 200 OK is the standard response for successful HTTP requests.?
• 3xx - Redirection: This class of status code indicates that the client must take additional action to complete the request, typically in the form of a redirect. Example: 301 Moved Permanently is used for permanent URL redirection.?
• 4xx - Client errors: These codes are intended for cases in which the client seems to have made an error. Example: 404 Not Found is perhaps the most well-known status code, indicating that the requested resource could not be found on the server.?
• 5xx - Server errors: These codes indicate cases in which the server is aware that it has encountered an error or is otherwise incapable of performing the request. Example: 500 Internal Server Error is a generic error message, given when no more specific message is suitable.?

It's important to note that although these conventions are widely adopted, they are not strictly enforced. Any server can return any code, so each application should be prepared to handle any status code that comes its way.?

Real-Life Examples of REST APIs in Azure and Power BI?

Now, let's look at some real-life examples of how REST APIs are used in Azure and Power BI.?

• Automated Dataset Refresh: You can automate the refresh of a Power BI dataset by setting up a script to make a POST request to the datasets/{datasetId}/refreshes endpoint at specific intervals. This way, you can ensure your data is always up to date, without needing to manually trigger a refresh.?
• Managing Embed Tokens: If you're embedding Power BI dashboards or reports into an application, you'll need to generate embed tokens. By automating this process with the GenerateToken endpoints (reports/{reportId}/GenerateToken for reports, dashboards/{dashboardId}/GenerateToken for dashboards), you can improve efficiency and make your code cleaner.?
• Bulk Operations: If you're dealing with many datasets, reports, or dashboards at once, you can use the API to perform bulk operations. For example, you could retrieve all datasets in a workspace with the groups/{groupId}/datasets endpoint, then loop through the returned list to perform actions on each one.?
• Error Handling: You can use the API to retrieve the status of dataset refreshes and identify any errors that occurred. The datasets/{datasetId}/refreshes endpoint provides information on the last eight refreshes of the specified dataset, allowing you to automatically monitor and handle errors.?
• Automate report generation: You can create a process that automatically generates and populates a Power BI report with data. For example, you might use the imports endpoint to import a PBIX file, then use the datasets/{datasetId}/tables/{tableName}/rows endpoint to add data to the report.?

Remember, when working with the Power BI REST API, you'll need to handle authentication. This typically involves registering an application in the Azure portal, then using the application's credentials to obtain an access token from Azure's OAuth 2.0 endpoint.?

These examples show just a few ways that the Power BI REST API can help streamline your developer’s life. Depending on your specific needs, there may be many other ways to leverage the API to improve efficiency and effectiveness. ?

Conclusion?

In the world of web services, REST APIs play a vital role in enabling different software applications to communicate and share data with each other. Azure and Power BI are just two of the countless services that use REST APIs extensively, providing developers a standard, structured, and efficient way of interacting with their resources.?

By now, you should have a basic understanding of REST APIs and how they function. Remember, every REST API revolves around the concepts of resources, endpoints, HTTP methods, and status codes. Understanding these fundamentals is the key to leveraging the power of REST APIs in your web applications. From business intelligence developer perspective, leveraging Power BI REST API can by real game changer for your day-to-day development.?

?