Introduction

SWOOP provides an API which you can use to extract data which appears in the SWOOP dashboards. When you use the SWOOP API you are provided with full access to the API. It may be necessary to restrict access to the application which is making the API request to a select part of the API.

This articles discusses the Azure offering to do this for you. There are other similar products around which do the same sort of thing (e.g. Google Apigee).

Getting Started

The first step is to create and Azure API Management service if you do not already have one you want to use.

The instructions for doing this are here:

https://docs.microsoft.com/en-us/azure/api-management/get-started-create-service-instance

You need only follow the instructions under 'Create a new service'.

Create an API

The process here is to create a new API which uses the SWOOP API as the back-end.

The instructions for doing this generically are here under 'Create an API':

https://docs.microsoft.com/en-us/azure/api-management/add-api-manually

These steps need to be adjusted for the SWOOP API as follows:

1. Navigate to your API Management service in the Azure portal and select APIs from the menu.
2. From the left menu, select + Add API.
3. Select Blank API from the list.
   
4. Enter settings for the API. The settings are explained in the Import and publish your first API tutorial.
5. Select Create.
6. Fill in in the form like this:
   
   *Note: replace 'swoop' in 'swoop.swoopanalytics.com' with your name (e.g. 'acme.swoopanalytics.com).  This applies to the rest of this article.
   
   Note: There is generally nothing critical about these values except for the 'Web service URL' which we are going to extend and override later.

Add an operation

Here we will add an operating to query 'Most Engaging Posts' in the 'Enterprise' mode.

The example API call is as follows:

https://<your name>.swoopanalytics.com/v1/api/Enterprise/MostEngagingPosts?DateFrom=2020-01-01&DateTo=2020-02-01

You will also need the token for the SWOOP API (refer to SWOOP API documentation).

1. Select the API you created in the previous step.
2. Click + Add Operation.
3. In the URL, select GET and enter "/mep" in the resource.
4. Enter "Most Engaging Posts" for Display name.
5. Select Save.

Now we need to configure the back end:

1. Click on edit (pencil) next to Backend
2. Click Override and copy the example API from above into the Service URL
3. Select Save
4. Click on Inbound processing'  / + policy'
5. Select Set headers
6. Add a new header for authorisation:
   
   Name: Authorization 
   Value:  Bearer <your token>
   Action: append
   
   
7. Select Save

Test an operation

Test the operation in the Azure portal:

1. Select the Test dashboard.
2. Select Most Engaging Posts
3. Press Send.

If this does not work please select Trace and inspect Back-end to ensure request is correct.

Executing the operation

You will need a Subscription token to execute the operation.  To do this:

1. Click on Subscriptions and + Add Subscription - you do not need to select a User/
2. Press Save
3. Click on ... next to the subscription (RHS) and then Show/hide keys.
4. Copy one of the keys.

You can execute your API with curl as follows:

curl -H "Ocp-Apim-Subscription-Key: <key>" <request URL from test above>