API reference

Data Migrator exposes a REST API for use by external clients. These API resources provide equivalent functionality to the commands described in the Command reference except for the commands related to metadata migrations.

You can access the API documentation for Data Migrator directly on your host machine while Data Migrator is running:
http(s)://<ldm-hostname>:<ldm-port>/ldm-api.html

Your ldm-hostname must be 127.0.0.1 or localhost by default.

URL for Swagger-based REST API documentation on your server:

http://localhost:18080/ldm-api.html

To access the API documentation from your system's public IP address, follow the steps below.

Access REST API documentation on your network

Data Migrator's API documentation can only be viewed from the Data Migrator host machine by default. This prevents unauthorized access from other machines. However, if you need to access the documentation from another system over your network, take the following steps:

1. Open /etc/wandisco/livedata-migrator/application.properties.

2. Delete or comment out the server.address=127.0.0.1 line.

3. Save the file changes.

4. Restart the Data Migrator service to apply the change. See System service commands - Data Migrator.

5. Check that access to the documentation is now available on your network:

   Example

   http://<ldm-hostname>:18080/ldm-api.html
   

   Replace ldm-hostname with the host name or IP address of the system running the livedata-migrator service.

6. (Optional) Once you have finished using the documentation, consider restoring the server.address entry to secure its access.

Metadata migrations

info

If you have upgraded to 2.6, properties controlling access to the Swagger docs on the Hivemigrator API have changed. Ensure your micronaut.security.intercept-url-map values in /etc/wandisco/hivemigrator/application.properties match the new default values for 2.6. See Configuration property changes in the release notes for the new default values.

Commands related to metadata migrations (such as hive agent, hive rule, hive migration) work through a different REST API port.

Access the API documentation for metadata migrations on your host machine:

http(s)://<hvm-hostname>:<hvm-port>/docs

Your hvm-hostname must be 127.0.0.1 or localhost by default.

Example

http://localhost:6780/docs

note

Your hivemigrator service host name is the same as your livedata-migrator service host, but you must use port 6780 instead of port 18080 to connect to the hivemigrator host.

Access metadata migration API documentation on your network

API documentation for metadata migration can only be viewed from the host machine by default. This prevents unauthorized access from other machines. However, if you need to access the documentation from another system over your network, take the following steps:

1. Open /etc/wandisco/hivemigrator/application.properties.

2. Delete or comment out the line micronaut.server.host=127.0.0.1.

3. Save the file changes.

4. Restart the Hive Migrator service to enable the new configuration. See System service commands - Hive Migrator.

5. Check that access to the documentation is now available on your network:

   Example

   http://hvm-hostname:6780/docs
   

   Replace hvm-hostname with the host name or IP address of the system running the hivemigrator service.

6. (Optional) Once you have finished using the documentation, consider restoring the server.address entry to secure its access.

Accessing endpoints with common web client tools

You can also access the API endpoints listed in the Swagger API reference interface using commonly available tools such as cURL.

Example, cURL request to the /stats endpoint.

curl -X 'GET' 'http://10.6.123.124:18080/stats'

Find all endpoints and methods available for your current version, along with examples, by viewing the Data Migrator Swagger API reference or Hive Migrator Swagger API reference.

If you've applied Basic Authentication or API LDAP Access control, construct your requests with either Basic or Bearer authentication.

Using Basic authentication

Example: Basic authentication using cURL, create filesystem.

curl -u admin:password -X 'POST' 'http://<host>:18080/fs/targets/adls2/shared-key/adlsTarget%20?listenAndApplySourceChanges=false' -H 'accept: application/json -H 'Content-Type: application/json' -d '{"sharedKey":"ThisIsAShar3rK3y==", "endpoint": "dfs.core.windows.net", "accountName": "mYAccount", "containerName": "container1", "insecure": false, "additionalProperties": { "fs.azure.concurrentRequestCount.in": "4", "fs.azure.write.request.size": "16384"}}'

Using Bearer authentication

Obtain a JSON Web Token using the /authentication/authenticate endpoint, then supply the token with your request.

Example: Retrieve JWT

curl -u admin:password -H 'POST' 'http://<host>:18080/authentication/authenticate' -H 'accept: application/json' -H 'Content-Type: application/json' -d '{"userName": "John.Smith@company.com","password": "pass123"}'

Example, create filesystem request with bearer authentication using cURL

curl -H "Authorization: Bearer eyJhbGB3arerTok3nExampl3y7gieWA" \
-X 'POST' \
'http://<host>:18080/fs/targets/adls2/shared-key/adlsTarget%20?listenAndApplySourceChanges=false' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"sharedKey":"ThisIsAShar3rK3y==", "endpoint": "dfs.core.windows.net", "accountName": "mYAccount", "containerName": "container1", "insecure": false, "additionalProperties": { "fs.azure.concurrentRequestCount.in": "4", "fs.azure.write.request.size": "16384"}}'