Recent pages

Edit
page

New
sub-page

Print
page
This page was modified over a year ago by James (User:James)
0
21
4

API Reference

Table of contents
  2. 1. Get_Ticket
  3. 2. Authorize Session
  • 1. Downloading a File from Box.Net
  • 2. Saving a File to Box.Net
      1. 2.1. Logout
      2. 2.2. Register_New_User
      3. 2.3. Get_Account_Tree
      4. 2.4. Export_Tags
      5. 2.5. Create_Folder
      6. 2.6. Move
      7. 2.7. Rename
      8. 2.8. Delete
      9. 2.9. Public_Share
      10. 2.10. Public_Unshare
      11. 2.11. Private_Share
      12. 2.12. Add_To_MyBox
      13. 2.13. Add_To_Tag
      14. 2.14. Set_Description
      15. 2.15. Get_File_Info
      16. 2.16. Get_Friends
      17. 2.17. Request_Friends

    • From Doc



     You'll need to choose between using REST, SOAP, and XML-POST for each API call.



    REST Setup



    REST Request:
    		         www.box.net/api/1.0/rest?action=actionvalue&param=paramvalue&param=paramvalue



    XML Setup



    XML Request:
    		 <request>
    <action>actionvalue</action>
    <input>inputvalue</input>
    <input>inputvalue</input>
    </request>




    For SOAP Setup, refer to the W3C documentation (http://www.w3schools.com/soap/default.asp).






    Session Initiation



    Get_Ticket


    The ticket is a unique string identifying your session. You'll only need it for initial authorization.





    Positive Response <status>get_ticket_ok</status>
    <ticket>bxquuv025arztljze2n438md9zef95e8</ticket>
    Negative Response <status>application_restricted</status>





    Authorize Session


    Unless you retrieve stored auth tokens (Glossary) saved in a database or cookie, you'll need to redirect the user to Box.net to sign in.




                                                                                        After retrieving ticket, redirect to:   http://www.box.net/api/1.0/auth/<ticket>




    Response Example:       www.webapp.com/?api_key=292u47372101037ds&auth_token=287hs8js91110ka871





    Web Apps: The auth token is appended onto the end of the callback URL (Glossary).



    Desktop Apps: Use Get Auth Token (Getting Started/Get Auth Token) procedure.



    Once you have an auth token, you're ready for file procedures.

    Basic Procedures





    Downloading a File from Box.Net


      Downloading a file is as easy as making a GET request:




    Saving a File to Box.Net


      Once you've authorized a session, you can send a file to Box with an HTTP POST request.




    Sample HTML <form action="http://upload.box.net/api/1.0/upload/0ef4e2b1be630554ffa4044c054b1954/756"
    enctype="multipart/form-data" method="POST">
    <input type="file" name="new_file1" />
    <input type="file" name="new_file2" />
    <input type="submit" name="upload_files" value="Upload File" />
    </form>
    Positive Response <status>upload_ok</status>
    <files>
    <file file_name="minutes.doc" id="5996" folder_id="756" shared="0" public_name="">
    </files>
    Negative Response <status>application_restricted</status>
    <status>not_logged_id</status>
    <status>upload_some_files_failed</status>
    (this one is often the result of exceeding filesize or filespace limits)







    Advanced Procedures


    Logout


    Logout your user after finishing API interaction, for greater security.








    Positive Response <status>logout_ok</status>
    Negative Response <status>invalid_auth_token</status>




    Register_New_User


    Register a new user.


    • Input: API Key (Glossary) 
    • Input: Login (E-mail Address - string)
    • Input: Password (







    Positive Response <status>successful_register</status>
    <auth_token>successful_register</auth_token>
    <user>
    <login>email@example.com (mailto:email@example.com)</login>
    <email>email@example.com (mailto:email@example.com)</email>
    <access_id>398387</access_id>
    <user_id>398387</user_id>
    <space_amount>222893011</space_amount>
    <space_used>26420</space_used>
    </user>
    Negative Response <status>invalid_auth_token</status>


    Get_Account_Tree


    Get the Account Tree. This is a critical first step for file-related API calls.


    • Input: API Key (Glossary) 
    • Input: Auth Token (Glossary) 
    • Input: Folder ID (default to "0")
    •  Params[]: onelevel - make a tree of one level depth, so you will get only files and folders stored in folder which folder_id you have provided.
                     nofiles - include folders only in result tree, no files.
                     nozip - do not zip tree xml.







    Positive Response <folder id="0" name = "school files" shared="1">
    <tags><tag id="3"></tags>
    <folders>
    <folder id="4384" name="Anthropology_304" shared="0">
    <tags><tag id="4"></tags>
    <files>
    <file id="3899" file_name="essayfinaldraft.pdf" keyword="anthroessay" shared="0" size="288881" created=
    "5020001" updated="50350028"    >
    <tags><tag id="4" name="nativesocieties"></tags>
    </file>
    </files>
    </folders>
    </folder>
    Negative Response <status>application_restricted</status>
    <status>e_folder_id</status>
    <status>not_logged__id</status>


    Export_Tags


    Export Tags.








    Positive Response <status>export_tags_ok</status>
    <tags><tag id="4">anthropology</tags>
    Negative Response <status>application_restricted</status>
    <status>e_folder_id</status>
    <status>not_logged__id</status>


    Create_Folder


    Create a new folder.


    • Input: API Key (Glossary) 
    • Input: Auth Token (Glossary) 
    • Input: Parent_ID (Parent Folder ID, default set to "0")
    • Input: Name
    • Input: Share (default set to "0")







    Positive Response <status>create_ok</status>
    <folder>
    <folder_id>738</folder_id>
    <folder_name>Lectures</folder_name>
    <folder_type>738</folder_type>
    <user_id>452</user_id>
    <path></path>
    <shared>1</shared>
    <public_name>diukss8</public_name>
    <show_comments></show_comments>
    <parent_folder_id>0</parent_folder_id>
    <password></password>
    </folder>
    Negative Response <status>application_restricted</status>
    <status>e_no_parent_folder</status>
    <status>not_logged__in</status>




    Move


    Move a file or folder to a different location within an account.


    • Input: API Key (Glossary) 
    • Input: Auth Token (Glossary) 
    • Input: Target (either "file" or "folder")
    • Input: Target_ID
    • Input: Destination_ID








    Positive Response <status>s_move_node</status>
    Negative Response <status>application_restricted</status>
    <status>e_move_node</status>
    <status>not_logged__in</status>





    Rename


    Rename a file or folder.


    • Input: API Key (Glossary) 
    • Input: Auth Token (Glossary) 
    • Input: Target (either "file" or "folder")
    • Input: Target_ID
    • Input: New_Name









    Positive Response <status>s_rename_node</status>
    Negative Response <status>application_restricted</status>
    <status>e_rename_node</status>
    <status>not_logged__in</status>





    Delete


    Rename a file or folder.


    • Input: API Key (Glossary) 
    • Input: Auth Token (Glossary) 
    • Input: Target (either "file" or "folder")
    • Input: Target_ID










    Positive Response <status>s_delete_node</status>
    Negative Response <status>application_restricted</status>
    <status>e_delete_node</status>
    <status>not_logged__in</status>



    Public_Share


    Share a file or folder.


    • Input: API Key (Glossary) 
    • Input: Auth Token (Glossary) 
    • Input: Target (either "file" or "folder")
    • Input: Target_ID
    • Input: Password (optional)
    • Input: Message
    • Input: Emails (array of recipients)










    Positive Response <status>share_ok</status>
    <public_name>hdkjsu7ob</public_name>
    Negative Response <status>application_restricted</status>
    <status>share_error</status>
    <status>wrong_node</status> 
    <status>not_logged__in</status>






    Public_Unshare


    Unshare a file or folder.


    • Input: API Key (Glossary) 
    • Input: Auth Token (Glossary) 
    • Input: Target (either "file" or "folder")
    • Input: Target_ID







    Positive Response <status>unshare_ok</status>
    Negative Response <status>application_restricted</status>
    <status>unshare_error</status>
    <status>wrong_node</status> 
    <status>not_logged__in</status>






    Private_Share


    Share a file or folder, privately.


    • Input: API Key (Glossary) 
    • Input: Auth Token (Glossary) 
    • Input: Target (must be "file", folders cannot be shared privately)
    • Input: Target_ID
    • Input: Message
    • Input: Emails (array of recipients)
    • Input: Notify (boolean to send notification e-mail to recipients)






    Positive Response <status>private_share_ok</status>
    <public_name>hdkjsu7ob</public_name>
    Negative Response <status>application_restricted</status>
    <status>private_share_error</status>
    <status>wrong_node</status> 
    <status>not_logged__in</status>







    Add_To_MyBox


    Add a publicly shared file to a user's box.


    • Input: API Key (Glossary) 
    • Input: Auth Token (Glossary) 
    • Input: Target (must be "file", folders cannot be shared privately)
    • Input: File_ID  (either this param of Public_Name)
    • Input: Public_Name (either this param or File_ID)
    • Input: Folder_ID (where file should be copied)
    • Input: Tags (Array, Added to copied file)







    Positive Response <status>addtomybox_ok</status>
    Negative Response <status>application_restricted</status>
    <status>addtomybox_error</status>
    <status>s_link_exists</status> 
    <status>not_logged__id</status>





    Add_To_Tag


    Add file or folder to tags list.


    • Input: API Key (Glossary) 
    • Input: Auth Token (Glossary) 
    • Input: Target ("file" or "folder")
    • Input: Target_ID
    • Input: Tags (Array)








    Positive Response <status>addtotag_ok</status>
    Negative Response <status>addtotag_error</status>







    Set_Description


    Set the description for a file or folder.


    • Input: API Key (Glossary) 
    • Input: Auth Token (Glossary) 
    • Input: Target ("file" or "folder")
    • Input: Target_ID
    • Input: Description









    Positive Response <status>s_set_description</status>
    Negative Response <status>e_set_description</status>






    Get_File_Info


    Get detailed information about a file.












    Positive Response <status>s_get_file_info</status>
    <info>
    <file_id>723</file_id>
    <file_name>Descartes.doc</file_name>
    <folder_id>70</folder_id>
    <shared>1</shared>
    <shared_name></shared_name>
    <size>74400138</size>
    <description></description>
    <sha1>3jdaso28ew8shjsshvnlspo2sb8</sha1>
    <created>1182159570</created>
    <updated>1182159571</updated>
    </info>
    Negative Response <status>e_access_denied</status>




    Get_Friends


    Get information about a user's friends.


    • Input: API Key (Glossary) 
    • Input: Auth Token (Glossary) 
    •  Params[]: nozip - do not zip tree xml.








    Positive Response <friends>
    <friend>
    <name>name@email.com (mailto:name@email.com)</name>
    <email>name@email.com (mailto:name@email.com)</email>
    <accepted>1</accepted>
    <avatar_url>    http://boxnet/index.php?rm=box_user_avatar&amp;user_id=398396&amp;width=40&amp;height=40&amp;type=large</avatar_url>
    <boxes>
    <box>
    <id>15</id>
    <url>http://box.net/p/name/</url>
    <status>0</status>
    </box>
    </boxes>