How to: Upload a work by HTTP POST

From Safe Creative API
Revision as of 10:26, 6 May 2010 by w>Jguillo
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

Call work.upload.begin to initiate the upload process

REQUEST:

https://upload01.safecreative.org/v2/
?authkey=1i5g2aaf2bz09lyo867cuimqg
&component=work.upload.begin
&uploadid=32fdc258-d822-43f1-9192-22fbb33c133a
&ztime=1271749853224
&signature=169c8e1d4348578ff07188c3040eb596fe5455ab

RESPONSE:

<?xml version="1.0" encoding="UTF-8"?>
<restvalueresponse>
  <state>ready</state>
</restvalueresponse>

Upload file chunks

You can upload the file by chunks with work.upload.chunk. You send the uploadid the offset and the data encoded in base64.

You can retry sending any chunk when it fails, you can send a chunk more than once and the send order of the chunks is not relevant

REQUEST:

https://upload01.safecreative.org/v2/
?authkey=1i5g2aaf2bz09lyo867cuimqg
&component=work.upload.chunk
&data=VmVyeSBsb25nIGZpbGU%3D
&offset=0
&uploadid=32fdc258-d822-43f1-9192-22fbb33c133a
&ztime=1271749853485
&signature=3db8efc39d5fa86ff438a638b83585377e136cb7

RESPONSE:

<?xml version="1.0" encoding="UTF-8"?> <workuploadchunk>

 <state>continue</state>

</workuploadchunk>

Finishing the upload

Once you have uploaded all chunks, you can commit the uploaded file using work.uplod.commit.

You must send the SHA1 checksum of the uploaded file for validation.

This component will return an upload ticket to be used later for registering the work.

REQUEST:

https://upload01.safecreative.org/v2/
?authkey=1i5g2aaf2bz09lyo867cuimqg
&checksum=9f9e051a32f6a773335a0cc1d4cf94d17b49faa6
&component=work.upload.commit
&length=14
&uploadid=32fdc258-d822-43f1-9192-22fbb33c133a
&ztime=1271749853854
&signature=9d9f8b51e73fec2364f9c08af7d5e526086dbd17

RESPONSE:

<?xml version="1.0" encoding="UTF-8"?>
<workuploadcommit>
  <uploadticket>HvWIbGj7anBOe9jBEyThJriUBVty_zu-dOyhOh--YmXAtfGZCEGRvZqs3HyW5_ZkpU7ZPfFYOhhqjNpON-EqT7mLzLL5IMHbbYrUdGztRd0KetgtOsZW_qZqR_Xnv68zn012s1ORd8izn-HK4HInC9uidLqj68kRjDNH28UkyC_HCLG5VfLktWGqm2zigYOhympUDUY4ZUJuFNKBqQhsFbpaTMQQvV5eB9HF2DauB3LmFCdxEYOZDg==</uploadticket>
</workuploadcommit>


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%2Fnc-sampling%2B%2F1.0%2F
&noncekey=5m5da8jt16gc7x9a3k0ede8hk
&obs=Obs+2
&registrypublic=1
&tags=tag1%2C+tag2
&title=My+first+long+registration
&uploadticket=HvWIbGj7anBOe9jBEyThJriUBVty_zu-dOyhOh--YmXAtfGZCEGRvZqs3HyW5_ZkpU7ZPfFYOhhqjNpON-EqT7mLzLL5IMHbbYrUdGztRd0KetgtOsZW_qZqR_Xnv68zn012s1ORd8izn-HK4HInC9uidLqj68kRjDNH28UkyC_HCLG5VfLktWGqm2zigYOhympUDUY4ZUJuFNKBqQhsFbpaTMQQvV5eB9HF2DauB3LmFCdxEYOZDg%3D%3D
&usealias=1
&userauthor=1
&worktype=article
&ztime=1271749859753
&signature=e62105771f8e329266db5fdc604580daa3e1094e

RESPONSE:

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