Overview
The API is currently setup to support two types of authentication: session authentication and token authentication. Session authentication is used with the web interface to the API, such that users can log in using the API's web GUI and they will be authenticated throughout their sessions.
Token authentication is for client access to the API, and works such that the client must make a request to a specific end point on the server with the username and password of the user. The server will then return an HTTP response with the token in the header. From then on, requests from the client to the server that require user authentication must have the token in the header of the request. The server will use the token to associate any activity with the user who has been granted that token.
(NOTE: This section is here for documentation sake, but using the Django Test Server is not necessary with the service running through IIS)
Starting the Django Test Server
Django includes a test web server to use during development. To start it, one must run the manage.py script in the project directory, telling it to run the server and passing it the correct IP address/port information. Specifically, at the command line,
cd into the project directory with the command $ cd /D D:\projects\ebagis\DatabaseInterfaceTesting\eBagis
run the server with the IP/port 0.0.0.0:8000 with the command $ python manage.py runserver 0.0.0.0:8000
keep the command window open as long as you want the server running; the process is attached to the command line window. If you want to stop the server, use Ctrl+c or close the window.
Getting a Token with cURL
cURL is a command line utility for sending HTTP requests. It has the advantage over the browser in that it can send all types of HTTP requests, including PUT and POST.
The cURL command to get a token is this:
$ curl -X POST --form username=<put_in_username> --form password=<put_in_password> https://webservices.geog.pdx.edu/api/rest/account/login/
Breaking this down, the -X tells curl the next argument defines the HTTP request type. In this case we want to POST. The --form tag goes before an element to be sent as HTML form data; the field name of the form data is to the left of the =, and the content for that field is to the right, such that is in the username example, username is the form field username, and the username that is entered is the entry for that field. The request to the the token only requires the two form elements shown here: username and password. The positional argument at the end of the command is the URL to which to send the request; the end point on the server for getting a user's token is api/rest/api-token-auth.
The response the server will return, with a valid username/password combo, should be JSON like this:
{"token": "0123456789abcdef0123456789abcdef01234567"}
The Header for Authenticated Requests
As mentioned, authenticated requests require a header that includes the token. The header should be like this:
Authorization: Token 0123456789abcdef0123456789abcdef01234567
The header can be included with any cURL requests by providing it with the option -H and wrapping it in '' to keep the spaces from breaking it apart into separate arguments to cURL.
Some Sample Authenticated Requests (replace the token with a real one)
Get the root of the REST API, which will return all available endpoints:
$ curl -X GET -H 'Authorization: Token 0123456789abcdef0123456789abcdef01234567' https://test.ebagis.geog.pdx.edu/api/rest/
Get the list of AOIs:
$ curl -X GET -H 'Authorization: Token 0123456789abcdef0123456789abcdef01234567' https://test.ebagis.geog.pdx.edu/api/rest/aoi/
Get the user's uploads:
$ curl -X GET -H 'Authorization: Token 0123456789abcdef0123456789abcdef01234567' https://test.ebagis.geog.pdx.edu/api/rest/upload/
Post an AOI upload:
$ curl https://test.ebagis.geog.pdx.edu/api/rest/aois/ -H 'Authorization: Token 0123456789abcdef0123456789abcdef01234567' -X POST --form "file=@C:\Docs\Lesley\aoi1_05222013.zip" --form filename=aoi1_05222013 --form md5=9832eb48462ba306f6d952558faeb4b9
Test sending a version in the header:
$ curl -X GET --header "Accept: application/json; version=0.1" https://test.ebagis.geog.pdx.edu/api/rest/api-version/
Putting a chunked upload:
$ curl https://test.ebagis.geog.pdx.edu/api/rest/aois/ -H 'Authorization: Token 0123456789abcdef0123456789abcdef01234567' -H 'Content-Range: bytes 0-3596856/3596856' -X PUT --form "file=@C:\Docs\Lesley\aoi1_01022018_2.zip" --form filename=aoi1_01022018_2
Post after a chunked upload (note md5 should be in lower-case):
$ curl https://test.ebagis.geog.pdx.edu/api/rest/uploads/21358bd4-9a06-43bb-a765-f212cf35b09b/ -H 'Authorization: Token a35eb5af3c794fa4bace923b3d1ed6ff3045e268' -X POST --form 'md5=d144d98f72eabaaa95ff2d2449d1cb38'
There is a proof-of-concept in progress for connecting to the REST API from VB .NET. The code may be found in the google code repository. As of this point in time, the code of interest is in the SecurityModule and FrmDownloadAoiMenu.vb.
Downloaded/installed Microsoft File Checksum Integrity Verifier to generate MD5 checksum value on Windows 7 before trying to upload:
fciv -md5 C:\Docs\Lesley\aoi1_05222013.zip
Error-handling through Visual Studio 2010 does not appear to be robust. I installed Fiddler Web Debugger to examine the request and response in detail. This provided better error-reporting than VS.