How to: Upload a work by HTTP POST

From Safe Creative API
Revision as of 11:26, 10 March 2016 by w>Jguillo (→‎Work registration)
Jump to navigation Jump to search

You can upload a work using a standard HTTP POST upload through an upload servlet.

You can also upload a work by chunks in case of very large files or unreliable connections.

Getting an upload server and ID

With work.upload.lookup you ask for an URL which you will use to upload the work. To upload by post, specify the parameter bypost=true

REQUEST

https://api.safecreative.org/v2/
?component=work.upload.lookup
&authkey=1i5g2aaf2bz09lyo867cuimqg
&bypost=true
&filename=my+file+name
&ztime=1271749837445
&signature=68b97266ea439203402ac496f27016a01878290a

RESPONSE

<?xml version="1.0" encoding="UTF-8"?>
<workuploadlookup>
  <uploadurl>http://upload01.safecreative.org/api-upload</uploadurl>
  <uploadid>c5866e13-6d9a-41a5-9578-eacba8c80e02</uploadid>
</workuploadlookup>

Upload the file

You must build a multipart HTTP POST request (Content-Type: multipart/form-data) to the URL returned by work.upload.lookup.

It must contain a standard parameter uploadid with the upload ID returned by work.upload.lookup and a file parameter file.

The servlet will return an upload ticket, with no XML enclosure.

REQUEST:

http://upload01.safecreative.org/api-upload
Content-Type: multipart/form-data; boundary=AaB03x

--AaB03x
Content-Disposition: form-data; name="uploadid"

3c33a96c-7743-43d0-9614-db70fa46d3ad
--AaB03x
Content-Disposition: file; name="file"; filename="file1.txt"
Content-Type: text/plain

These are the file contents
--AaB03x--

RESPONSE

HvWIbGj7anDefJK3tQHdPze8ekYaVUQJgKw_N6t0Wd_UblANNOjyVfkyK0fgPXRPgiR8SyVr7HmS4Uiiediu6MlFVYIcjUD0zc4Kc8m3e2Irr14iQi-A215pEaqlvOSZ6WUIbWvY-GD2e8akWxhESdnFG088_nUHEsAjkOvnF-ogK144M4vLuIj4Ylc6inW-80LNnqH10kh7zMJcxsv0lZzTMGrXa2pN

Check the uploaded file status

To ensure the registration will be successful, the uploaded file must be completely processed before attempting to call work.register. You can use work.uploadticket.status to get the status of the uploaded file. Processing time depends on the size of the file.

REQUEST:

https://api.safecreative.org/v2/
?component=work.uploadticket.status
&authkey=1i5g2aaf2bz09lyo867cuimqg
&uploadticket=HvWIbGj7anDefJK3tQHdPze8ekYaVUQJgKw_N6t0Wd_UblANNOjyVfkyK0fgPXRPgiR8SyVr7HmS4Uiiediu6MlFVYIcjUD0zc4Kc8m3e2Irr14iQi-A215pEaqlvOSZ6WUIbWvY-GD2e8akWxhESdnFG088_nUHEsAjkOvnF-ogK144M4vLuIj4Ylc6inW-80LNnqH10kh7zMJcxsv0lZzTMGrXa2pN
&ztime=1271749849300
&signature=369c1c8aa498f02b0e7aa03974164b212b00e961

RESPONSE:

<restvalueresponse>
  <state>ready</state>
</restvalueresponse>

Register the work

Now that the file has been uploaded, you can register the work.

Getting the nonce key

You need a nonce key to register the work:

REQUEST:

https://api.safecreative.org/v2/
?authkey=1i5g2aaf2bz09lyo867cuimqg
&component=authkey.state
&sharedkey=zy9x4ol0ctg3btyswq7b5wi9
&ztime=1271749859500
&signature=74ff075ff35b2a8bb0950780a483affdaa6d8544

RESPONSE:

<?xml version="1.0" encoding="UTF-8"?>
<authkeystate>
  <authkey>1i5g2aaf2bz09lyo867cuimqg</authkey>
  <level>MANAGE</level>
  <noncekey>5m5da8jt16gc7x9a3k0ede8hk</noncekey>
  <usercode>0907100000018</usercode>
  <authorized>true</authorized>
</authkeystate>

Work registration

Register the work by calling work.register.

You must provide the obtained upload ticket and nonce key and all relevant data about the work (title, work type, license, etc.)

REQUEST:

https://api.safecreative.org/v2/
?allowdownload=1
&authkey=1i5g2aaf2bz09lyo867cuimqg
&component=work.register
&excerpt=Very+long+text+about+registry+philosophy
&license=http%3A%2F%2Fcreativecommons.org%2Flicenses%2Fby%2F3.0%2F
&noncekey=5m5da8jt16gc7x9a3k0ede8hk
&obs=Obs+2
&registrypublic=1
&tags=tag1%2C+tag2
&title=My+first+long+registration
&uploadticket=HvWIbGj7anDefJK3tQHdPze8ekYaVUQJgKw_N6t0Wd_UblANNOjyVfkyK0fgPXRPgiR8SyVr7HmS4Uiiediu6MlFVYIcjUD0zc4Kc8m3e2Irr14iQi-A215pEaqlvOSZ6WUIbWvY-GD2e8akWxhESdnFG088_nUHEsAjkOvnF-ogK144M4vLuIj4Ylc6inW-80LNnqH10kh7zMJcxsv0lZzTMGrXa2pN
&userauthor=1
&worktype=article
&ztime=1271749859753
&signature=e62105771f8e329266db5fdc604580daa3e1094e

RESPONSE:

<?xml version="1.0" encoding="UTF-8"?>
<workregistry>
  <code>1004200146123</code>
</workregistry>