How to: Upload a work by HTTP POST: Difference between revisions

From Safe Creative API
Jump to navigation Jump to search
w>Jguillo
(Created page with '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 con…')
 
m (11 revisions imported)
 
(10 intermediate revisions by 2 users not shown)
Line 1: Line 1:
You can upload a work using a standard HTTP [[POST upload]] through an [[upload servlet]].
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.
You can also [[upload a work by chunks]] in case of very large files or unreliable connections.
Line 27: Line 27:
= Upload the file =
= Upload the file =


Call [[work.upload.begin]] to initiate the upload process
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:
REQUEST:
<nowiki>http://upload01.safecreative.org/api-upload</nowiki>
<pre>
<pre>
https://upload01.safecreative.org/v2/
Content-Type: multipart/form-data; boundary=AaB03x
?authkey=1i5g2aaf2bz09lyo867cuimqg
&component=work.upload.begin
&uploadid=32fdc258-d822-43f1-9192-22fbb33c133a
&ztime=1271749853224
&signature=169c8e1d4348578ff07188c3040eb596fe5455ab
</pre>


RESPONSE:
--AaB03x
<pre>
Content-Disposition: form-data; name="uploadid"
<?xml version="1.0" encoding="UTF-8"?>
<restvalueresponse>
  <state>ready</state>
</restvalueresponse>
</pre>


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


You can upload the file by chunks with [[work.upload.chunk]]. You send the uploadid the offset and the data encoded in base64.
These are the file contents
--AaB03x--
</pre>


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
RESPONSE
 
REQUEST:


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


RESPONSE:
= Check the uploaded file status =
 
<?xml version="1.0" encoding="UTF-8"?>
<workuploadchunk>
  <state>continue</state>
</workuploadchunk>


= Finishing the upload =
To ensure the registration will be successful, the uploaded file must be completely processed before attempting to call [[work.register]].
Once you have uploaded all chunks, you can commit the uploaded file using [[work.uplod.commit]].  
You can use [[work.uploadticket.status]] to get the status of the uploaded file. Processing time depends on the size of the file.
 
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:
REQUEST:
<pre>
<pre>
https://upload01.safecreative.org/v2/
https://api.safecreative.org/v2/
?authkey=1i5g2aaf2bz09lyo867cuimqg
?component=work.uploadticket.status
&checksum=9f9e051a32f6a773335a0cc1d4cf94d17b49faa6
&authkey=1i5g2aaf2bz09lyo867cuimqg
&component=work.upload.commit
&uploadticket=HvWIbGj7anDefJK3tQHdPze8ekYaVUQJgKw_N6t0Wd_UblANNOjyVfkyK0fgPXRPgiR8SyVr7HmS4Uiiediu6MlFVYIcjUD0zc4Kc8m3e2Irr14iQi-A215pEaqlvOSZ6WUIbWvY-GD2e8akWxhESdnFG088_nUHEsAjkOvnF-ogK144M4vLuIj4Ylc6inW-80LNnqH10kh7zMJcxsv0lZzTMGrXa2pN
&length=14
&ztime=1271749849300
&uploadid=32fdc258-d822-43f1-9192-22fbb33c133a
&signature=369c1c8aa498f02b0e7aa03974164b212b00e961
&ztime=1271749853854
&signature=9d9f8b51e73fec2364f9c08af7d5e526086dbd17
</pre>
</pre>


RESPONSE:
RESPONSE:
<pre>
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<restvalueresponse>
<workuploadcommit>
   <state>ready</state>
   <uploadticket>HvWIbGj7anBOe9jBEyThJriUBVty_zu-dOyhOh--YmXAtfGZCEGRvZqs3HyW5_ZkpU7ZPfFYOhhqjNpON-EqT7mLzLL5IMHbbYrUdGztRd0KetgtOsZW_qZqR_Xnv68zn012s1ORd8izn-HK4HInC9uidLqj68kRjDNH28UkyC_HCLG5VfLktWGqm2zigYOhympUDUY4ZUJuFNKBqQhsFbpaTMQQvV5eB9HF2DauB3LmFCdxEYOZDg==</uploadticket>
</restvalueresponse>
</workuploadcommit>
</pre>
</pre>


= Register the work =
= Register the work =
Line 144: Line 121:
&component=work.register
&component=work.register
&excerpt=Very+long+text+about+registry+philosophy
&excerpt=Very+long+text+about+registry+philosophy
&license=http%3A%2F%2Fcreativecommons.org%2Flicenses%2Fnc-sampling%2B%2F1.0%2F
&license=http%3A%2F%2Fcreativecommons.org%2Flicenses%2Fby%2F3.0%2F
&noncekey=5m5da8jt16gc7x9a3k0ede8hk
&noncekey=5m5da8jt16gc7x9a3k0ede8hk
&obs=Obs+2
&obs=Obs+2
Line 150: Line 127:
&tags=tag1%2C+tag2
&tags=tag1%2C+tag2
&title=My+first+long+registration
&title=My+first+long+registration
&uploadticket=HvWIbGj7anBOe9jBEyThJriUBVty_zu-dOyhOh--YmXAtfGZCEGRvZqs3HyW5_ZkpU7ZPfFYOhhqjNpON-EqT7mLzLL5IMHbbYrUdGztRd0KetgtOsZW_qZqR_Xnv68zn012s1ORd8izn-HK4HInC9uidLqj68kRjDNH28UkyC_HCLG5VfLktWGqm2zigYOhympUDUY4ZUJuFNKBqQhsFbpaTMQQvV5eB9HF2DauB3LmFCdxEYOZDg%3D%3D
&uploadticket=HvWIbGj7anDefJK3tQHdPze8ekYaVUQJgKw_N6t0Wd_UblANNOjyVfkyK0fgPXRPgiR8SyVr7HmS4Uiiediu6MlFVYIcjUD0zc4Kc8m3e2Irr14iQi-A215pEaqlvOSZ6WUIbWvY-GD2e8akWxhESdnFG088_nUHEsAjkOvnF-ogK144M4vLuIj4Ylc6inW-80LNnqH10kh7zMJcxsv0lZzTMGrXa2pN
&usealias=1
&userauthor=1
&userauthor=1
&worktype=article
&worktype=article

Latest revision as of 08:07, 7 May 2021

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>
Retrieved from "https://www.safecreative.org/mw/index.php?title=How_to:_Upload_a_work_by_HTTP_POST&oldid=309"