Mapping Assistant Web Service API Getting Started

Overview

The goal of this document is to help setup the mapping assistant web service.

In the examples we access the MAWS using the following URL.

http://localhost/maws

please adjust this to your actual host/application path.

For example we will use the following tools:

Step 1. Deploy maws, setup database and configuration settings

We need at least two empty databases, one for authentication and one for mapping store DB. The MAWS needs to know how to connect to those two databases. This is defined in the connection strings.

For the authentication database must have the authdb connection string name. For the Mapping Store DB the default name is MappingStoreServer but it can be anything, provided the query parameter sid=madb_connection_name is used when accessing SDMX REST API.

Step 2. Initialize the authentication database

This step needs to be run from localhost. In other words needs to executed the same machine where MAWS was deployed.

To do that we need to make the following HTTP request:

PUT auth/version/current HTTP/1.1
Content-Type: application/json

With body

{
  "version": "1.0"
}

Step 2 Windows Example

Example in powershell:

iwr http://localhost/maws/auth/version/current -Method PUT -ContentType 'application/json' -Body '{ "version": "1.0" }'

Step 2 Linux/Bash Example

Example in curl:

curl -i --request PUT --header 'Content-Type: application/json' --data '{ "version": "1.0" }' http://localhost/maws/auth/version/current

If everything went fine, the MAWS should respond with HTTP status code 201 Created

Step 3. Change admin password (optional)

During initialization an admin user is created with no password. Unless the installation is used for testing/presentation it is recommended that a password is set.

Please note the password is encoded to base64 in order to pass symbol characters on the wire. This is not encryption. For encrypting HTTPS should be used.

The password rules are set in the Web.Config file at passwordValidation app setting.

To change the password of a user we need to make the following HTTP request:

PUT auth/user/{username}/password HTTP/1.1
Content-Type: application/json
Authentication: Basic base64 of user:pass

Body:

{ "password"="<base64 encoding of password>" }

Response if everything goes well:

HTTP/1.1 204 No Content

Step 3 Windows Example

Example in powershell, it will set the admin password to MAWStest*1. Note this example will prompt for the existing password, which default is not set. Just press OK:

# first we encode the password to base64
$base64pass = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes('MAWStest*1'));

# then we send the request. Note a window will be shown got the existing admin password
$response=iwr -Uri http://localhost/maws/auth/user/admin/password -Credential (Get-Credential -UserName 'admin' -Message 'Enter admin password default nothing') -Method PUT -ContentType 'application/json' -Body (@{ password=$base64pass; } | ConvertTo-Json )

# see the output. If everything went fine, the status code will be 204
$response

Step 3 Linux/Bash Example

Example in curl

# first we encode the password to base64
base64pass=$(echo -n 'MAWStest*1' | base64)

# then we send the request and show the headers
curl -i --request PUT --user 'admin:' --header 'Content-Type: application/json' --data "{ \"password\": \"$base64pass\" }" http://localhost/maws/auth/user/admin/password

Step 4. Add the Mapping Assistant DB connection name (optional)

In step 1, we added to the Mapping Assistant Web service configuration a connection string to the Mapping Store database. In case the name is not MappingStoreServer then two steps are needed:

Step 4.1 Add the connection name to the Authentication DB

To add a connection name {storeId} to the authentication DB the following request needs to be send:

PUT auth/storeid/{storeid}
Content-Length: 0

In case it was created the response status code will be 201 Created. Else it will be 204 No Content

HTTP/1.1 201 Created

Step 4.1 Windows Example

For example in powershell we add the connection name/store id scratch.

$response=iwr -Uri http://localhost/maws/auth/storeid/scratch -Credential (Get-Credential -UserName 'admin' -Message 'Enter admin password default nothing') -Method PUT -ContentType 'application/json'
$response

Step 4.1 Linux/Bash Example

For example in bash we add the connection name/store id scratch.

curl -i --basic --request PUT --user 'admin:MAWStest*1' --header 'Content-Length: 0'  http://localhost/maws/auth/storeId/scratch

Step 4.2 Give user admin to access to mapping store

The user has a list of connection names that they can access. By default the user admin can access only the Mapping Assistant DB with connection string name MappingStoreServer. To allow the user to access to other Mapping Store DB which use a non-default connection string name, the user must be updated.

The actual request and the responses can be seen below using sample data. Further down are PowerShell and Curl examples

PUT /auth/user/{username}
Content-Type: application/json

With body:

{
  "user1":
  {
      "defaultStoreId" : "production",
      "accessRules": [ "CanReadData", "CanReadStructure" ],
      "storeIds": [ "production", "old_production" ]
  }
}

Update existing user response:

HTTP/1.1 204 No Content
Location: /auth/user/{username}

Create new user response:

HTTP/1.1 201 Created
Location: /auth/user/{username}

Step 4.2 Windows Example

Below is an example in powershell to allow the admin user to access the database configured with connection name scratch

# we login only once
$creds=(Get-Credential -UserName 'admin' -Message 'Enter Authentication DB admin password default nothing')
# first we get the user object
$adminUserResp=iwr -Uri http://localhost/maws/auth/user/admin -Credential $creds
# the we parse and modify the response
$j=($adminUserResp.Content | ConvertFrom-Json)
$j.admin.storeIds += 'scratch';

# update the user
$updateAdminResponse=iwr -Uri http://localhost/maws/auth/user/admin -Credential $creds -method PUT -Body ($j | ConvertTo-Json) -ContentType 'application/json'

Step 4.2 Linux/Bash Example

Below is an example in bash and curl to allow the admin user to access the database configured with connection name scratch

For Bash there is no standard way to parse and modify JSON. But being a text format it can be editted using a text editor. Alternative at tool like jq

# first get the user json
curl --user 'admin:MAWStest*1' http://localhost/maws/auth/user/admin -o admin-user.json

# Now we edit the admin-user.json with a text editor
# or use the jq tool to add it
jq '.admin.storeIds += ["scratch"]' admin-user.json > updated-admin-user.json

# update the user
curl -i --request PUT  --header 'Content-Type: application/json' --data @updated-admin-user.json  --user 'admin:MAWStest*1' http://localhost/maws/auth/user/admin

Step 5. Initialize the Mapping Store database

Final step is to initialize the Mapping Store DB. Because this step is destructive, it will delete all Mapping Store related tables and data, as first step we check the status of the Mapping store.

Step 5.1 Check if the connection string to mapping store DB is correctly configured

GET store/{sid}/status HTTP/1.1

Where {sid} is the connection string name.

If the MA WS can access the Mapping Store DB then the response should have status code 200 OK. If it fails then please verify that the connection string with the corresponding name is correct.

Step 5.1 Windows example

For connection string name scratch:

# get the status. The StatusCode should 200. The $creds we got from a previous example
iwr -Uri http://localhost/maws/store/scratch/status -Credential $creds

Step 5.1 Linux/Bash example

For connection string name scratch:

# get the status
curl -i --user 'admin:MAWStest*1' http://localhost/maws/store/scratch/status

The response should have

HTTP/1.1 200 OK

Step 5.2 Get the current version

If the previous step was successful we double check if the target database has the Mapping Store schema applied.

GET store/{sid}/version HTTP/1.1

Where {sid} is the connection string name.

If the target database does not have a Mapping Store Schema then the response should have status code 404. Else if it does have, then the response would be 200 with the version as a response for example:

HTTP/1.1 200 OK
Content-Length: 24
Content-Type: application/json; charset=utf-8
Date: Thu, 21 Jun 2018 14:03:43 GMT

{
  "version": "6.4"
}

Step 5.2 Windows example

For connection string name scratch:

# get the status. The StatusCode should be 404. The $creds we got from a previous example
iwr -Uri http://localhost/maws/store/scratch/version -Credential $creds

If there is no Mapping Store schema then response will look like an error like:

iwr : Store id doesn't point to a mapping store database

This is ok. It means that we need to initialize it.

Else if the StatusCode is 200 then it means there is a mapping store database and version is included in the response. e.g.

StatusCode        : 200
StatusDescription : OK
Content           : {
                      "version": "6.4"
                    }
RawContent        : HTTP/1.1 200 OK

Step 5.2 Linux/Bash example

For connection string name scratch:

# get the version
curl -i --user 'admin:MAWStest*1' http://localhost/maws/store/scratch/version

If there is no Mapping Store schema on the target database the response will have status code 404 e.g.

HTTP/1.1 404 Not Found

But if there is a Mapping Store Schema the response will have status code 200 and the Mapping Store schema version.

HTTP/1.1 200 OK
Content-Length: 24
Content-Type: application/json; charset=utf-8
Date: Fri, 22 Jun 2018 11:13:53 GMT

{
  "version": "6.4"
}

Step 5.3 Initialize the mapping store database

WARNING IMPORTANT READ FIRST This will delete and recreate all Mapping Store Schema related tables. Tables on those tables will deleted. Even if the previous step didn't find a Mapping Store schema. If there is a chance that the database may contain any useful data, please take a backup before initializing.

The actual request and the responses can be seen below using sample data. Further down are PowerShell and Curl examples

POST store/{sid}/status
Content-Type: application/json

Step 5.3 Windows example

Example for initializing the database that is referenced in the connection string with name scratch The $creds have been set in an earlier step.

iwr http://localhost/maws/store/scratch/status -Method POST -ContentType 'application/json' -Body '{ "initialize": true }' -Credential $creds

And if everything goes well the response will be 200 OK

Step 5.3 Linux/Bash

Example for initializing the database that is referenced in the connection string with name scratch

 curl -i --user 'admin:MAWStest*1' -X POST --header 'Content-Type: application/json' --data '{ "initialize" : true }' http://localhost/maws/store/scratch/status

And if everything goes well the response will be 200 OK