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:
- a PowerShell command
Invoke-WebRequestalso known asiwr, see documentation - The command line tool
curlwhich is found in many Linux distrubutions and in Git For Windows. See documentation
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/jsonWith 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/currentIf 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:passBody:
{ "password"="<base64 encoding of password>" }Response if everything goes well:
HTTP/1.1 204 No ContentStep 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
$responseStep 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/passwordStep 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: 0In case it was created the response status code will be 201 Created. Else it will be 204 No Content
HTTP/1.1 201 CreatedStep 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'
$responseStep 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/scratchStep 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/jsonWith 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/adminStep 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.1Where {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 $credsStep 5.1 Linux/Bash example
For connection string name scratch:
# get the status
curl -i --user 'admin:MAWStest*1' http://localhost/maws/store/scratch/statusThe response should have
HTTP/1.1 200 OKStep 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.1Where {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 $credsIf there is no Mapping Store schema then response will look like an error like:
iwr : Store id doesn't point to a mapping store databaseThis 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 OKStep 5.2 Linux/Bash example
For connection string name scratch:
# get the version
curl -i --user 'admin:MAWStest*1' http://localhost/maws/store/scratch/versionIf there is no Mapping Store schema on the target database the response will have status code 404 e.g.
HTTP/1.1 404 Not FoundBut 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/jsonStep 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 $credsAnd 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/statusAnd if everything goes well the response will be 200 OK