Contents
In today’s automated world, you probably can’t avoid using REST API’s in some way. More and more vendors offer their products supported by REST API’s, to take full advantage in automation and integration into other products and services. If you’re new to REST API’s and wonder how to use them, this post has you covered.
What is a REST API?
As the name states, it’s a programming interface. This means, you can interact with an application or a web service in an automated (and usually non-interactive) way. Let’s assume you a script in which you need the current exchange rate of a currency. Instead of manually checking the rate on a website and fill that value into your script, you could automatically fetch the current rate using a REST API from an exchange platform. There are many different ways to interact with a REST API, from requesting data to uploading data to modifying data.
Why should I use REST API’s?
Because REST API’s work by using generic HTTP methods, you can use them wherever you can web requests, e.g. your web browser or PowerShell. Any web portal, for example the Azure portal, communicates using REST API’s in the background (you can track the web requests using the networking tab in your browsers dev tools). If you visit a website in your browser, your browser simply runs a GET request to the webserver and gets the website content as a response.
Therefore, especially in automation, you can use them with almost every scripting or programming langue – you won’t be dependent on some specific modules or libraries, you can even use them with simple PowerShell commands like Invoke-RestMethod.
Components of a REST API
A REST API usually consists of the following parts:
{URI-scheme} :// {URI-host} / {resource-path} ? {query-string}
URI scheme: Indicates the protocol, since REST API’s are usually web based, this will be http or https
URI host: Specified the service endpoint which is an FQDN or an IP address
Resource path: This part differs from API to API. It usually includes values to describe further information like specific resources or environments or even specific actions like list, write, etc.
Query string: With the query string you’re able to send specific queries with your request, depending on the API. It usually includes an API version to target aswell. For example: https://example.com/api/users?name=marco
The structure and components of a REST API differ from vendor to vendor. Usually, REST API’s come with decent documentation nowadays.
As you learned above, REST API’s provide a way to interact with a service, which most of the time requires some sort of authentication and authorization.
Quick reminder
Authentication: Process of verifying who a user is
Authorization: Process of verifying what a user has access to
Reasons why need to authenticate might be:
- Anonymus access is not allowed
- You access your own data
- You have a paid access/plan to the API
- There’s a throttling on free API calls you want to overcome
Again, the way you authenticate against your API depends on the vendor. Normally you need to obtain an access token (also known and used as bearer token) first and send it with your API call in the request headers. We’ll take a look on that in a later blog post. Other forms of authentication are personal access tokens (PAT) or simple access keys.
How do I find out which URI to call?
As mentioned above, vendors usually have some documentation alongside their API’s. When we take a look at the Azure DevOps Services REST API documentation, the definition for querying health state information looks like this:
GET https://status.dev.azure.com/_apis/status/health?services={services}&geographies={geographies}&api-version=7.0-preview.1
The first part defines the HTTP Method GET, followed by de URI and its components. There are two placeholders services and geographies, which you can use to further target specific information. Let’s assume we want to know the health state of the services Core services, Repos and Pipelines in the Region West Europe, the URI resolves like to this:
https://status.dev.azure.com/_apis/status/health?services=core services,repos,pipelines&geographies=EU&api-version=7.0-preview.1
You can now simply copy and paste this URI into your web browser and view the results. Using PowerShell for REST calls is fairly simple aswell, you can use the standard module Invoke-RestMethod for that:
Invoke-RestMethod -Method Get "https://status.dev.azure.com/_apis/status/health?services=core services,repos,pipelines&geographies=EU&api-version=7.0-preview.1"
Depending on the REST API, the response is already properly formatted, most of the time you need to work with the data and do some parsing yourself. Let’s only show the health state without any other information:
(Invoke-RestMethod -Method Get "https://status.dev.azure.com/_apis/status/health?services=core services,repos,pipelines&geographies=EU&api-version=7.0-preview.1").status
End result:
Conslusion
REST API’s provide a way to interact with applications and services in an automated way, which is especially suitable when using scripting and programming languages. API’s are becoming more and more important, especially in the coming time.
I hope you now have a good first overview of REST API’s. We’ll cover some deeper usage and specifically the Azure and Microsoft Graph API’s in further articles.