How to: Upload a work by chunks

File upload process

You can upload a work using the components work.upload.lookup, work.upload.begin, work.upload.chunk and work.upload.commit or using a standard HTTP POST upload through an upload servlet.

We encourage to use the POST upload, but in case of very large files or unreliable connections, the chunk upload described below may be better.

Getting an upload server and ID

With work.upload.lookup you ask for an URL which you will use to upload the work.

REQUEST:

https://api.safecreative.org/v2/
?authkey=1i5g2aaf2bz09lyo867cuimqg
&component=work.upload.lookup
&filename=long.txt
&ztime=1271749852968
&signature=0b0f8008b61a412bf90f48cae7d42294751c8a56

RESPONSE:

<?xml version="1.0" encoding="UTF-8"?>
<workuploadlookup>
  <uploadurl>http://upload01.safecreative.org</uploadurl>
  <uploadid>32fdc258-d822-43f1-9192-22fbb33c133a</uploadid>
</workuploadlookup>

From this point on you will use the uploadurl to invoke the work.upload.begin, work.upload.chunk and work.upload.commit functions.

Starting the upload process

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.upload.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>