Windocks REST API
Windocks provides an authenticated (token based) API to create and manage SQL Server containers with database clones. The Windocks web application uses the same API so if you need a reference application for the REST API, open the web app in a browser, navigate to windocks\ui\index.html and inspect the page and debug the Network requests. Windocks is based on a port of docker’s open source container project, with several of the APIs based on the APIs (such as create, remove, ps, etc). This doc includes curl samples (Download curl for Windows from here ). There are also working Curl samples in the product in windocks\samples\curlSamples.
The Windocks API is accessed on the IP address of the machine running the Windocks services - port 3000 (3001 for SSL based access). The SSL based access requires the Windocks server configured with a certificate and a domain record. To setup SSL access to the web app, open the file windocks\gateway\config.js and put in the values for sslCertificateFile and sslKeyFile, and create those files in the paths specified by you. The REST API is accessed at IpAddressOfWindocksServer:3000 (or IpAddressOfWindocksServer:3001 for SSL). Please email support@windocks.com to get the default administrator password
Obtaining the access token
/windocks
Method: POST
Content type: application/json
Request payload:
{“Data”:”action=bizexec&bizexectype=authlogin&bizparameters=username~password”}
Response payload:
{"Success":true,”Data":"success=1&result=1~yourauthtoken"}
Use the token for the requests below (Everything after but not including the ~ up until the ending but not including the " is the token)
CURL:
Create a file named getauthtoken.json and put the following inside it:
{ "Data": "action=bizexec&bizexectype=authlogin&bizparameters=administrator~youradministratorpassword" }
Then cd to the same directory as the file getauthtoken.json and run the curl command below:
curl -H "Content-Type: application/json" -d@getauthtoken.json -X POST http://localhost:3000/windocks
This will return your access token in the form {"Success":true,”Data":"success=1&result=1~yourauthtoken"}. Everything after but not including the ~ up until the end but not including the "} is the token
Validating an access token
/windocks
Method: POST
Content type: application/json
Request payload:
{“Data”:”action=bizexec&bizexectype=authvalidatetoken&bizparameters=token”}
Response payload:
{"Success":true,”Data":"success=1&result=succeeded"}
CURL:
Create a file named validateauthtoken.json and put the following inside it:
{ "Data": "action=bizexec&bizexectype=authvalidatetoken&bizparameters=token" }
Then cd to the same directory as the file validateauthtoken.json and run the curl command below:
curl -H "Content-Type: application/json" -d@validateauthtoken.json -X POST http://localhost:3000/windocks
This will return your access token in the form {"Success":true,”Data":"success=1&result=succeeded"}.
View all images (command line: docker images)
/images/json?token=yourauthtoken
Method: GET
Content type: application/json
Response payload:
[
{
"Id":"41001a81-d88a-4d22-b08a-7421808fb0f0",
"ParentId":"", "RepoTags":["newimage:none"],
"RepoDigests":null,
"Created":1546888558,
"Size":0,
"VirtualSize"0,
"Labels":null,
"CloneData”:”windocks_clone_image^customers^reportserverssrs_1-6-19^report
serverssrs_1-6-19_tempdb"
},
….
]
CURL:
curl -H "Content-Type: application/json" -X GET http://localhost:3000/images/json?token=youraccesstoken
List all containers (command line: docker ps)
/containers/json?all=1&token=yourauthtoken
Method: GET
Content type: application/json
Response payload:
[
{
"Id":"c727e32ceff8e6615abfbdc67c4067759a1256e953695476460fef9242911a40",
"Names":["/myname1/Windocks-id:cb7c1cab-2d80-4e34-8405-9bf340c60595"], "Image":"myimagename1",
“Created":1546888558,
"Ports":[{"IP":"","PrivatePort":10001,"PublicPort":10001,"Type":""}],
"Status":"Started",
"Sqlinfo": "encrypted sa password"
},
….
]
CURL:
curl -X GET "http://localhost:3000/containers/json?all=1&token=youraccesstoken"
CURL for list container filtered by container name:
curl -G -X GET "http://localhost:3000/containers/json" --data-urlencode token=yourtoken --data-urlencode all=1 --data-urlencode filters={\"name\":[\"yourcontainername\"]}
Build image (docker build -t yourimagename path\to\directory\containing\docker\file )
/build?t=yourimagename&token=yourauthtoken
METHOD: POST
Content-Type: application/tar
Request payload: (tar of dockerfile and other files needed for build)
Response payload (sample):
{
"stream": "Step 0 : FROM mssql-2016\n”
}
{
"stream":"ContainerId = 42ed48f47558e7bb6624dd4cf173543063eaea5e514b75c62ff1d7c0f34f7929 & ContainerPort = 10004 & ContainerUserName = prison_oo_owH8Hlp & MSSQLPort = 10004”
}
{
"stream":" & DockerFile output: & Image yourimagename created. Please run docker create yourimagename OR docker run -d yourimagename to get fresh containers from the image you just created”
}
CURL:
First create a tar gzip of the dockerfile and any other files needed for the build. In a command line:
cd directory\containing\dockerfile
tar -cvzf nameoftargzippedfile.tar.gz *
Then make the build API call
curl -H "Content-Type: application/x-tar" -v -X POST "http://localhost:3000/build?t=yournewimagename&token=youraccesstoken" --data-binary @nameoftargzippedfile.tar.gz
Delete image (command line: docker rmi)
/images/yourimagename?token=yourauthtoken
Method: DELETE
CURL:
curl -H "Content-Type: application/json" -X DELETE http://localhost:3000/images/imagenametodelete?token=youraccesstoken
View all containers (command line: docker ps)
/containers/json?all=1&token=yourauthtoken
Method: GET
Content type: application/json
Response payload:
[
{
“Id":"a8ab2462c02c80f5091473da5551f3498527c64fd28607c6ea079e56e6f9bafe",
“Names":["/admiring_sammet/ Windocks-id:cd6ad9c0-f5ab-4a18-9371-a17114a5064f"],
“Image":"ssrs_1-6-19",
“Created":1546810419,
“Ports":[{"IP":"",
“PrivatePort":10005,
“PublicPort":10005,
“Type":""}],
“Status":"Started",
“Clones":"customers^\\\\WINDOCKS\\cd6ad9c0-f5ab-4a18-9371-a17114a5064fssrs_1-6- 19\\customerscustomerdata.mdf^\\\\WINDOCKS\\cd6ad9c0f5ab-4a18-9371- a17114a5064fssrs_1-6-19\\customerscustomerdata_log.ldf! reportserverssrs_1-6- 19^\\\\WINDOCKS\\cd6ad9c0-f5ab-4a18-9371a17114a5064fssrs_1-6- 19\\reportserverssrs_1-6-19ReportServer10001.mdf^\\\ \WINDOCKS\\cd6ad9c0-f5ab-4a18-9371-a17114a5064fssrs_1-6-19\ \reportserverssrs_1-6-19ReportServer10001_log.ldf!reportserverssrs_1-6-19_tempdb^\\ \\WINDOCKS\\cd6ad9c0-f5ab-4a18-9371-a17114a5064fssrs_1-6-19\ \reportserverssrs_1-6-19_tempdbReportServer10001TempDB.mdf^\\\\WINDOCKS\ \cd6ad9c0-f5ab-4a18-9371-a17114a5064fssrs_1-6-19\ \reportserverssrs_1-6-19_tempdbReportServer10001TempDB_log.ldf",
“Sqlinfo":"none"
}
........
]
CURL:
curl -H "Content-Type: application/json" -X GET "http://localhost:3000/containers/json?all=1&token=youraccesstoken"
Create container (command line: docker create)
/containers/create?name=nameyouwant&token=yourauthtoken
Method: POST
Content type: application/json
Request payload:
If you want to specify the port for the container put it in ExposedPorts (like port 10031 below). If you don't want to specify a port then set "ExposedPorts": {}
If you want to set the sa / root password for the database container, then follow the example below in Env
If you want to select particular databases from the image to deliver in the container, then follow the example SQL_DB_NAME_OVERRIDES below.
If you do not want to set any Env, then set "Env": []
{
"AttachStdout": false,
"AttachStderr": false,
"ExposedPorts": {"10031/tcp":{}},
"Env": ["SQL_DB_NAME_OVERRIDES=customers,vendors", "SA_PASSWORD=saPass123@"],
"Image": "s1",
"HostConfig":
{
"NetworkMode": "bridge",
"RestartPolicy": {"Name": "no"}
}
}
Response payload:
{
“Id": "ContainerId = cd03021ea80a092b48eb157f2ad1ab13b584ebc174066a4c460252e78a1c0c4e& ContainerPort = 10006 &ContainerUserName=prison_oo_HVQ9dj8& MSSQLREPORTPort = 10006 & clones = customers^\\\\WINDOCKS\\a1950056eb81- 4d3f-a7fb-db0251fd2878ssrs_1-6-19\\customerscustomerdata.mdf^\\\ \WINDOCKS\\a1950056-eb81-4d3f-a7fb-db0251fd2878ssrs_1-6-19\ \customerscustomerdata_log.ldf!reportserverssrs_1-6- 19^\\\\WINDOCKS\\a1950056eb81-4d3f-a7fb-db0251fd2878ssrs_1-6-19\ \reportserverssrs_1-6-19ReportServer10001.mdf^\\\\WINDOCKS\\a1950056-eb81- 4d3fa7fb-db0251fd2878ssrs_1-6-19\\reportserverssrs_1-6- 19ReportServer10001_log.ldf! reportserverssrs_1-6-19_tempdb^\\\\WINDOCKS\\a1950056-eb81-4d3fa7fbdb0251fd2878ssrs_1-6-19\ \reportserverssrs_1-6-19_tempdbReportServer10001TempDB.mdf^\\\\WINDOCKS\ \a1950056-eb81-4d3f-a7fb-db0251fd2878ssrs_1-6-19\ \reportserverssrs_1-6-19_tempdbReportServer10001TempDB_log.ldf”, "Warnings":null
}
CURL:
Create a file named create.json and put the following inside it (Replace youraccesstoken, yourcontainername, secret123@, and 10032 with your values) :
{ "AttachStdout": false, "AttachStderr": false, "ExposedPorts": {"10032/tcp":{}}, "Env": ["SA_PASSWORD=secret123@"],"Image": "yourimagename", "HostConfig": {"NetworkMode": "bridge", "RestartPolicy": {"Name": "no"}}}
Then run the curl command below:
curl -H "Content-Type: application/json" -d@create.json -X POST "http://localhost:3000/containers/create?name=yourcontainername&token=youraccesstoken"
This will create a container from the image named yourimagename (must already exist) at the port 10032 with admin password of secret123@
Start container (command line: docker rm)
/containers/firstthreelettersofdockercontaineridOrFullContainerName/start?token=yourauthtoken
Method: POST
CURL sample:
Parse the response from the above create API and get the container Id or you can use the container name to avoid parsing.
curl -H "Content-Type: application/json" -X POST http://localhost:3000/containers/firstthreelettersofdockercontaineridOrFullContainerName/start?token=youraccesstoken
Stop container (command line: docker stop)
/containers/firstthreelettersofdockercontaineridOrFullContainerName/stop?t=10&token=yourauthtoken
Method: POST
CURL sample:
curl -H "Content-Type: application/json" -X POST "http://localhost:3000/containers/firstthreelettersofdockercontaineridOrFullContainerName/stop?t=10&token=youraccesstoken"
Commit container (command line: docker commit)
/commit?container=firstthreelettersofdockercontaineridOrFullContainerName&comment=message&repo=newImageName&token=youraccesstoken
Method: POST
CURL sample:
curl -H "Content-Type: application/json" -X POST "http://localhost:3000/commit?container=firstthreelettersofdockercontaineridOrFullContainerName&comment=message&repo=newImageName&token=youraccesstoken"
View image log
/windockswrapper?token=youraccesstoken
Method: POST
CURL sample:
Create a file named getimagelog.json and put the following inside it:
{ "Data": "{\"action\": \"imagelog\", \"imagelog\": {\"imagename\": \"yourImageName\"}} " }
Then run the curl command below:
curl -H "Content-Type: application/json" -d@getimagelog.json -X POST http://localhost:3000/windockswrapper?token=youraccesstoken
View container log
/windockswrapper?token=youraccesstoken
Method: POST
CURL sample:
Create a file named getcontainerlog.json and put the following inside it:
{ "Data": "{\"action\": \"containerlog\", \"containerlog\": {\"containerid\": \"yourFullContainerId\"}} " }
Then run the curl command below:
curl -H "Content-Type: application/json" -d@getcontainerlog.json -X POST http://localhost:3000/windockswrapper?token=youraccesstoken
Refresh a SQL Server image with transaction log backups
/containers/yourimagename/exec?token=youraccesstoken
Method: POST
CURL sample:
Create a file named refresh.json and put the following inside it:
{ "AttachStdout": true, "AttachStdin": true, "AttachStderr": true, "Cmd": ["C:\\path\\to\\directory\\containing\\transaction\\logs"]}
Then run the curl command below:
curl -H "Content-Type: application/json" -d@refresh.json -X POST "http://localhost:3000/containers/yourimagename/exec?token=youraccesstoken"
Get refreshes applied on the automated schedule for the specified date range
/windocksdashboard?token=youraccesstoken
Method: POST
CURL sample:
Create a file named getruns.json and put the following inside it. Change the start and end epoch times (seconds since Jan 1 1970 - see https://www.epochconverter.com/):
{ "Data": "{\"action\": \"getruns\", \"payload\": {\"startEpoch\": 1617750120, \"endEpoch\": 1618009320}} " }
Then run the curl command below:
curl -H "Content-Type: application/json" -d@getruns.json -X POST "http://localhost:3000/windocksdashboard?token=youraccesstoken"
Prune an image which has had several transaction log backups applied already
/containers/yourimagename/exec?token=youraccesstoken
Method: POST
CURL sample:
Create a file named refresh.json and put the following inside it:
{ "AttachStdout": true, "AttachStdin": true, "AttachStderr": true, "Cmd": ["pruneupdates"]}
Then run the curl command below:
curl -H "Content-Type: application/json" -d@refresh.json -X POST "http://localhost:3000/containers/yourimagename/exec?token=youraccesstoken"