Let's take a tour of the API with cURL on the command-line from a linux workstation. For this demostration we are going to use a fictional API key, and a fictional user named franklin.
Please note that this is meant as a demonstration of our system and not as an interactive tutorial.
Query the API
Request
curl --digest -u 'franklin:password' https://api.datawitness.net/dw
Response
<?xml version="1.0" encoding="UTF-8"?>
<response status="fail">
<error>Invalid Developer Key</error>
</response>
So we can see that we are missing the API Key. Lets add this to a header:
curl --digest -u 'franklin:password' \
-H 'X-Datawitness-Key: key="5baa61e4c9b94g4g0683360b6cf8441b7dw68fd8"' \
https://api.datawitness.net/dw
Now we get:
<?xml version="1.0" encoding="UTF-8"?>
<response status="fail">
<error>Incorrect username or password.</error>
</response>
We see a new error. We have an incorrect username or password.
Each user must authenticate your application to act on his/her behalf. To do this, you must give the user access to the Datawitness API login page so they may authorize your application to act on their behalf.
To do this, you generate a URL on your site which directs each user to Datawitness to authorize your application, and also provide a callback URL for Datawitness to redirect the user to on completion of the authorization. The callback url is an HTTP GET including the users authorization token as a single argument. A fully constructed URL would look like this:
https://api.datawitness.net/login.php?app=5baa61e4c9b94g4g0683360b6cf8441b7dw68fd8
&next=http://YOURSITE.COM/URL/PAGE
The response URL will look like this:
http://YOURSITE.COM/URL/PAGE?authId=5c7fc449af8d971c9070d9d4147f517d
For the purposes of this demonstration (as we are using cURL) this step is assumed to be done. Let's try again but this time with the correct password:
curl --digest -u 'franklin:5c7fc449af8d971c9070d9d4147f517d' \
-H 'X-Datawitness-Key: key="5baa61e4c9b94g4g0683360b6cf8441b7dw68fd8"' \
https://api.datawitness.net/dw
<?xml version="1.0" encoding="UTF-8"?>
<response status="ok">
<Workflows>
<workflow>
<url>/tags</url>
<title>tags</title>
</workflow>
<workflow>
<url>/archives</url>
<title>archives</title>
</workflow>
</Workflows>
</response>
Good. We now have access to the currently available workflows. As this API gets extended, more URL's will show up here. Now that we have access, lets move on to doing something useful. First, let's look at the tags:
Tags
Tags are a great help to users as they allow for organization structures which circumvent traditional structures. Any User may organize and add objects for retrieval via multiple user-defined criteria. Let's Look at the Datawitness Tags functionality:
curl --digest -u 'franklin:5c7fc449af8d971c9070d9d4147f517d' \
-H 'X-Datawitness-Key: key="5baa61e4c9b94g4g0683360b6cf8441b7dw68fd8"' \
https://api.datawitness.net/dw/tags
<?xml version="1.0" encoding="UTF-8"?>
<response status="ok">
<Tags>
<tag>
<id>3</id>
<text>wallpapers</text>
</tag>
<tag>
<id>4</id>
<text>test data</text>
</tag>
...
</Tags>
</response>
So, we can GET a list of tags, and we can also POST to this URL to add a tag
curl --digest -u 'franklin:5c7fc449af8d971c9070d9d4147f517d' \
-H 'X-Datawitness-Key: key="5baa61e4c9b94g4g0683360b6cf8441b7dw68fd8"' \
-X POST \
-d "text=NewTag" \
https://api.datawitness.net/dw/tags
<?xml version="1.0" encoding="UTF-8"?>
<response status="ok">
<tag>
<id>74</id>
</tag>
</response>
Lets look at tag 3:
curl --digest -u 'franklin:5c7fc449af8d971c9070d9d4147f517d' \
-H 'X-Datawitness-Key: key="5baa61e4c9b94g4g0683360b6cf8441b7dw68fd8"' \
https://api.datawitness.net/dw/tags/3
<?xml version="1.0" encoding="UTF-8"?>
<response status="ok">
<Tags>
<tag>
<id>3</id>
<text>wallpapers</text>
<count>4</count>
<ctime>1184978464</ctime>
<mtime>1193413510</mtime>
</tag>
</Tags>
</response>
The Count references how many files this tag is associated to. It can be linked to using something like /dw/archives/tag/tag_id.
For now, lets get back to this tag. I think wallpapers should have a Capital "W". Lets POST to this URL With a new Value:
curl --digest -u 'franklin:5c7fc449af8d971c9070d9d4147f517d' \
-H 'X-Datawitness-Key: key="5baa61e4c9b94g4g0683360b6cf8441b7dw68fd8"' \
-X POST \
-d "text=Wallpapers" \
https://api.datawitness.net/dw/tags/3
<?xml version="1.0" encoding="UTF-8"?>
<response status="ok">
<Tags>
<tag>
<id>3</id>
<mtime>1193782019</mtime>
</tag>
</Tags>
</response>
Great! We can edit tags and add tags. Now lets look at archives:
Archives
Performing a GET request to /dw/archives will fetch a listing of all archives belonging to the current user:
curl --digest -u 'franklin:5c7fc449af8d971c9070d9d4147f517d' \
-H 'X-Datawitness-Key: key="5baa61e4c9b94g4g0683360b6cf8441b7dw68fd8"' \
https://api.datawitness.net/dw/archives
<?xml version="1.0" encoding="UTF-8"?>
<response status="ok">
<Files>
<file>
<id>5559</id>
<name>01236_blueprint_1280x1024.jpg</name>
<title>Blueprint #2</title>
</file>
<file>
<id>2252</id>
<name>ExpenseSheet.xls</name>
<title>Expense Sheet v2</title>
</file>
...
</Files>
</response>
Let’s add a file to our archives. To do this, we will be sending some required custom headers and performing a PUT of the file to have it added to the Datawitness archives.
curl --digest -u 'franklin:5c7fc449af8d971c9070d9d4147f517d' \
-H 'X-Datawitness-Key: key="5baa61e4c9b94g4g0683360b6cf8441b7dw68fd8"' \
-H 'X-Datawitness-Title: My Neat File' \
-H 'X-Datawitness-Name: file1.txt' \
-H 'Expect:' \
-T file1.txt \
https://api.datawitness.net/dw/archives
<?xml version="1.0" encoding="UTF-8"?>
<response status="ok">
<file>
<id>5562</id>
</file>
</response>
Some things to note here. We pass an empty Expect: header as we have not implemented the Expect: parameter on the Datawitness Webserver at the moment. We may change this in the future.
If any of the custom headers are missing an appropriately labelled error message will be returned.
Ok, now let’s look at an individual files details:
curl --digest -u 'franklin:5c7fc449af8d971c9070d9d4147f517d' \
-H 'X-Datawitness-Key: key="5baa61e4c9b94g4g0683360b6cf8441b7dw68fd8"' \
https://api.datawitness.net/dw/archives/5562
<?xml version="1.0" encoding="UTF-8"?>
<response status="ok">
<Files>
<file>
<id>5562</id>
<ticket>2a54f9a70b</ticket>
<title>My Neat File 2</title>
<name>file1.txt</name>
<full_size>891</full_size>
<mimetype>text/plain</mimetype>
<hash>d532e81630d0c587e0ae2b9721de68e4</hash>
<atime>1195597456</atime>
<mtime>1195597456</mtime>
<ctime>1195597456</ctime>
<parent_folder>0</parent_folder>
<tag id="81" text="SampleTag" />
<tag id="10" text="Semester 2" />
<tag id="11" text="Transcripts" />
<tag id="3" text="Wallpaper" />
</file>
</Files>
</response>
We get a fair bit of information from this query. Probably the most important piece of information is the ticket as it is required for downloading.
Let's GET this file:
curl --digest -u 'franklin:5c7fc449af8d971c9070d9d4147f517d' \
-H 'X-Datawitness-Key: key="5baa61e4c9b94g4g0683360b6cf8441b7dw68fd8"' \
https://api.datawitness.net/dw/archives/5562/2a54f9a70b
What we get back is the actual data of the file with the headers specifying the content-type,length and filename:
Last-Modified: Tue Nov 20 14:27:51 PST 2007
Date: Wed Nov 21 14:29:17 PST 2007
Content-Length: 891
Content-Transfer-Encoding: binary
Content-Type: text/plain
Content-Disposition: attachment; filename="file1.txt"
Accept-Ranges: bytes
Cache-Control: maxage=3600
Pragma: public
Expires: Wed, 21 Nov 2007 23:29:17 GMT
[ FILE DATA ]
...
The response can be passed to a file handle for use on your system.