Skip to content
Integraties en configuratie

vBoxxCloud API- en authenticatiereferentie

8 min. lezen

Met de vBoxxCloud API werk je rechtstreeks met vBoxxCloud. Via de API kun je veilig bestanden lezen en schrijven, accounts en organisaties aanmaken, bewerken en verwijderen, activiteit bijwerken en bekijken, roots openen en aanmaken en gegevens over machines opvragen. Alle functies van vBoxxCloud heb je zo binnen handbereik via de vBoxxCloud API.

De nieuwe vBoxxCloud API 2 is hier beschikbaar.

De referentie voor authenticatie in vBoxxCloud [vind je hier](/api/oauth2).

Aan de slag

Om bestanden te openen moeten we weten wie je bent, zodat we weten welke rechten je hebt. Daarvoor stuur je je gebruikersnaam en wachtwoord met een POST naar onze auth-URL. Je krijgt dan een token terug dat je aan andere methodes meegeeft. De belangrijkste URL's zijn dezelfde als de account/info- en metadata-URL's van de Dropbox API.

Een API-token ophalen

Om het API-token op te halen moet het HTTP POST-verzoek de gebruikersnaam en het wachtwoord bevatten. Lukt de authenticatie, dan krijg je het sessietoken terug; anders zie je een foutmelding.

Stel dat je server draait op web.vboxx.nl. Vraag een sessietoken aan door je gebruikersnaam en wachtwoord als POST-variabelen mee te sturen naar de volgende URL (let op de /1/: dat is het versienummer van de API):

     https://web.vboxx.nl/1/auth?username=&password=

Een geslaagd antwoord ziet er zo uit:

{
    "success":true,
    "session_token":                                                                 "GWObmeSrkWxGtCje0Mv27PcIkkwMydPSrY2d8yksfjonP7jg6eHgscUrBtMnoV584FFCyQPGXbHyetKmjWvBVIppUqQirBUVZCeJnLoIJgtabS4jyl1zsrcimqJCp7RY"
}

Laat je de POST-variabelen voor gebruikersnaam en wachtwoord weg, dan krijg je deze fout:

{
     "message": "You must provide a username and password",
     "success": false
}

Een onjuiste combinatie van gebruikersnaam en wachtwoord geeft deze fout:

{
     "message": "Invalid username or password",
     "success": false
}

Het API-token geldt alleen voor de huidige sessie; voor elke sessie heb je een nieuw token nodig. Aanmaken, lezen, bijwerken en verwijderen is bovendien beperkt tot de rechten van wie het API-token aanvraagt. Vraagt een systeembeheerder een API-token aan, dan heeft die toegang tot alle organisaties en alle acties daarbinnen. Vraagt een gebruiker een API-token aan, dan kan die geen nieuwe organisaties aanmaken, geen beleid instellen en ook verder niets op organisatieniveau wijzigen.

Hieronder een paar voorbeelden van wat je met het token kunt doen.

Accountgegevens ophalen

Om de accountgegevens van de huidige gebruiker (dus wie het API-token heeft aangevraagd) op te halen, gebruik je het URL-formaat /1/account/info/ . De volledige URL ziet er zo uit (met de voorbeeldhost van hierboven)

     https://web.vboxx.nl/1/account/info/?session_token=DFx9Hm5K2IQ8PK2s5Qwd5gY72EyHblYKbJSRhk04QxkyYl7nRptnE0psCjKtElPkKRjvXl0O6uzekLj6x3YWX6M9aSPQFrx5iVqHigoofeTu6PJoeWTfwJFbjCN625sv

Het antwoord ziet er ongeveer zo uit:

{
     "id": 1, 
     "first_name": "Karel", 
     "last_name": "de Groot", 
     "display_name": "Karel ",
     "email": "demouser@vboxx.nl" 
     "root_id": 1, 
     "space_usage": 3169361, 
     "space_usage_formatted": "3.02M", 
     "space_quota": null, 
     "space_quota_formatted": null, 
     "roots": 
     [ {
     "type": "backup", 
     "space_used": 718334, 
     "id": 4, 
     "name": "C:\\Projects\\backups\\greensnake\\greensnake\\static\\images" 
     }, {
     "type": "backup", 
     "space_used": 150048, 
     "id": 5, 
     "name": "C:\\Projects\\dropdav" 
     }, {
     "type": "backup", 
     "space_used": 1596688, 
     "id": 6, 
     "name": "C:\\Projects\\wsgidav" 
     }, {
     "type": "sync", 
     "space_used": 704291, 
     "id": 1, 
     "name": "Files" 
     }, {
     "type": "share", 
     "space_used": 0, 
     "id": 2, 
     "name": "Team Share 1" 
     }, {
     "type": "share", 
     "space_used": 0, 
     "id": 3, 
     "name": "Team Share 2" 
     }
     ], 
     "success": true,
} 

Bestanden en mappen in een root weergeven

Om de bestanden en mappen in de standaardroot weer te geven (dus de bestanden en mappen in de synchronisatiemap), gebruik je dit GET-verzoek:

     https://web.vboxx.nl/1/metadata/1/?session_token=DFx9Hm5K2IQ8PK2s5Qwd5gY72EyHblYKbJSRhk04QxkyYl7nRptnE0psCjKtElPkKRjvXl0O6uzekLj6x3YWX6M9aSPQFrx5iVqHigoofeTu6PJoeWTfwJFbjCN625sv

Het antwoord ziet er dan zo uit:

{
"hash": "71595dc2e15ae7b9924b60662f166108ccc588c3", 
"rev": 0, 
"thumb_exists": false, 
"modified_unix_timestamp": 0, 
"path": "/", 
"is_dir": true, 
"client_mtime": 0, 
"size": "0B", 
"is_deleted": false, 
"bytes": 0, 
"modified": 0, 
"contents": [ {
"rev": 0, 
"thumb_exists": false, 
"modified_unix_timestamp": 0, 
"path": "/documents", 
"is_dir": true, 
"client_mtime": 0, 
"size": "0B", 
"is_deleted": false, 
"bytes": 0, 
"modified": 0, 
"icon": "folder", 
"root": 1
}, {
"rev": 0, 
"thumb_exists": false, 
"modified_unix_timestamp": 0, 
"path": "/pictures", 
"is_dir": true, 
"client_mtime": 0, 
"size": "0B", 
"is_deleted": false, 
"bytes": 0, 
"modified": 0, 
"icon": "folder", 
"root": 1
}, {
"rev": 10, 
"thumb_exists": false, 
"modified_unix_timestamp": 1353459846, 
"path": "/vBoxxCloud.jpg", 
"is_dir": false, 
"client_mtime": "2012-11-20T17:04:06", 
"size": "1.91k", 
"is_deleted": false, 
"bytes": 1953, 
"modified": "2012-11-20T17:04:06", 
"icon": "page_white_picture", 
"root": 1
}
], 
"status_code": 200, 
"icon": "folder", 
"root": 1
}

Bestanden en mappen in een map van een bepaalde root weergeven

Om de bestanden en mappen in een map naar keuze weer te geven, gebruik je dit URI-formaat: /1/metadata/root_id/path/>session_token=session_token. Een voorbeeld:

     https://web.vboxx.nl/1/metadata/1/documents/?session_token=DFx9Hm5K2IQ8PK2s5Qwd5gY72EyHblYKbJSRhk04QxkyYl7nRptnE0psCjKtElPkKRjvXl0O6uzekLj6x3YWX6M9aSPQFrx5iVqHigoofeTu6PJoeWTfwJFbjCN625sv

Hier is de standaardroot (/1/) opgegeven, en de map "documents" staat in de standaardroot.

Deellinks en downloadlinks maken

Om een deellink naar een volledige root te maken, gebruik je deze URI:

     https://web.vboxx.nl/1/shares/create_link/1/?session_token=DFx9Hm5K2IQ8PK2s5Qwd5gY72EyHblYKbJSRhk04QxkyYl7nRptnE0psCjKtElPkKRjvXl0O6uzekLj6x3YWX6M9aSPQFrx5iVqHigoofeTu6PJoeWTfwJFbjCN625sv

Om een deellink naar een map binnen een root te maken:

     https://web.vboxx.nl/1/shares/create_link/1/documents/?session_token=DFx9Hm5K2IQ8PK2s5Qwd5gY72EyHblYKbJSRhk04QxkyYl7nRptnE0psCjKtElPkKRjvXl0O6uzekLj6x3YWX6M9aSPQFrx5iVqHigoofeTu6PJoeWTfwJFbjCN625sv

Om een deellink naar een specifiek bestand in een map in een root te maken:

     https://web.vboxx.nl/1/shares/create_link/1/documents/abc.txt?session_token=DFx9Hm5K2IQ8PK2s5Qwd5gY72EyHblYKbJSRhk04QxkyYl7nRptnE0psCjKtElPkKRjvXl0O6uzekLj6x3YWX6M9aSPQFrx5iVqHigoofeTu6PJoeWTfwJFbjCN625sv

Om een link te maken om een specifiek bestand te downloaden:

     https://web.vboxx.nl/1/files/1/documents%2Fabc.txt?session_token=DFx9Hm5K2IQ8PK2s5Qwd5gY72EyHblYKbJSRhk04QxkyYl7nRptnE0psCjKtElPkKRjvXl0O6uzekLj6x3YWX6M9aSPQFrx5iVqHigoofeTu6PJoeWTfwJFbjCN625sv

Geïmplementeerde endpoints

Basis-URI:

//management/

Foutmeldingen zien er zo uit en hebben een HTTP-statuscode die overeenkomt met de status_code :

{
    "status_code": 404,
    "message": "unknown root with id 20",
    "code": "error" 
}
{
    "status_code": 500,
    "message": "missing required field activity_type_id",
    "code": "error" 
}

Persoon

/person/ - haalt de gegevens van de huidige gebruiker op

/person// - haalt de gegevens op van de gebruiker met het opgegeven id, als de huidige gebruiker daar rechten voor heeft

/person//full/ - haalt de "volledige" gegevens op van de gebruiker met het opgegeven id, als de huidige gebruiker daar rechten voor heeft. Zo wordt bijvoorbeeld het bedrijf volledig ingevuld in plaats van alleen het id van het bedrijf

/person/create/- maakt een nieuwe persoon aan met de volgende parameters:

NaamVerplichtInfo
company_idjabedrijfs-id voor de nieuwe persoon
first_namejavoornaam van de nieuwe persoon
last_namejaachternaam van de nieuwe persoon
emailjae-mailadres van de nieuwe persoon
passwordjawachtwoord van de nieuwe persoon
space_quotaneeopslagquotum van de nieuwe gebruiker als geheel getal
mobile_phoneneemobiele nummer van de nieuwe gebruiker
mobile_service_provider_idneeid van de mobiele provider van de nieuwe gebruiker
site_adminneetrue of false om de nieuwe gebruiker site_admin-rechten te geven
system_adminneetrue of false om de nieuwe gebruiker system_admin-rechten te geven
create_rootneetrue of false om automatisch een root voor de nieuwe gebruiker aan te maken

voorbeeld van een geslaagd antwoord:

{
    "full_uri": "/1/management/person/31/full/",
    "root_created": false,
    "code": "success",
    "id": 31,
    "uri": "/1/management/person/31/" 
}

/person/update/- werkt een bestaande persoon bij met de volgende parameters (id is de enige verplichte parameter):

Naam
id
first_name
last_name
company_id
space_quota
email
password
mobile_phone
mobile_service_provider_id
system_admin
site_admin

voorbeeld van een geslaagd antwoord:

{
    "full_uri": "/1/management/person/31/full/",
    "code": "success",
    "id": 31,
    "uri": "/1/management/person/31/" 
}

Activiteit

/activity/types/ - geeft de soorten activiteiten in het systeem weer

voorbeeldantwoord:

[
    {
        "id": 1,
        "activity": "added account",
        "machine_scope": false,
        "user_scope": false,
        "system_scope": false
    },
    {
        "id": 10,
        "activity": "added auth source to",
        "machine_scope": false,
        "user_scope": false,
        "system_scope": false
    },
    ....
}

/activity/// - geeft de activiteiten terug voor een entity_type "organization" of "person" met het opgegeven id. Geeft maximaal 10 activiteiten terug, samen met het totale aantal activiteiten, het huidige paginanummer en het aantal pagina's. Zie het voorbeeldantwoord hieronder

/activity///page// - hetzelfde als hierboven, maar geeft pagina page_name van de activiteitsresultaten terug in plaats van pagina 1

voorbeeldantwoord:

{
    "activities" : [
        {
            "id": 69,
            "acted_on_type": "person",
            "acted_on_text": "api_created_first api_created_last",
            "actor_type": "person",
            "actor_company_id": null,
            "actor_machine_id": null,
            "actor_person_id": 2,
            "actor_text": "Michel Jansen",
            "data_text": null,
            "created": "2012-10-17T16:23:26.598000+00:00",
            "acted_on_machine_id": null,
            "acted_on_company_id": 2,
            "acted_on_person_id": 20,
            "acted_on_root_id": null,
            "num_alerts": 0,
            "action_text": "removed account" 
        },
        ....
    ],
    "total_activities": 25,
    "total_pages": 3,
    "page": 1
}

/activity// - haalt de activiteit met het opgegeven id op

voorbeeldantwoord:

{
    "id": 3,
    "actor_type": null,
    "actor_text": "System",
    "actor_company_id": null,
    "actor_machine_id": null,
    "actor_person_id": null,
    "action_text": null,
    "acted_on_type": "site",
    "acted_on_text": "All Organizations",
    "acted_on_company_id": 1,
    "acted_on_machine_id": null,
    "acted_on_person_id": null,
    "data_text": "C:/vBoxxCloudDBStore",
    "activity_type_id": 22,
    "created": "2012-10-04T22:40:37.182000+00:00",
    "acted_on_root_id": null
}

/activity/create/- maakt een activiteit aan met de volgende parameters

NaamVerplichtInfo
activity_type_idjaid van het activiteitstype
actor_idjaid van de actor, geïnterpreteerd volgens de parameter actor_type
actor_typejatype actor, moet op dit moment 'person', 'site' of 'machine' zijn
acted_on_idjaid van de entiteit waarop de actie betrekking heeft, geïnterpreteerd volgens de parameter acted_on_type
acted_on_typejatype entiteit waarop de actie betrekking heeft, moet op dit moment 'person', 'site', 'machine' of 'root' zijn
actor_textneeoptionele extra tekst
acted_on_textneeoptionele extra tekst
data_textneeoptionele extra tekst

voorbeeldantwoord:

{
    "code": "success",
    "id": 34,
    "uri": "/1/management/activity/34/" 
}

Beleid

/policy// - haalt het beleid met het opgegeven id op, op dit moment is dat een company_id, maar dat verandert waarschijnlijk in de toekomst

voorbeeldantwoord:

{
    "space_quota": 1073741824,
    "max_file_size": "300",
    "purge_deleted": false,
    "trim_revisions": false,
    "excluded_extensions": ".$$,.$db,.113,.3g2,.3gp,...." 
    "company_id": 2,
    "purge_deleted_frequency": "",
    "user_trim_revisions": false,
    "user_create_backups": false,
    "id": 2,
    "trim_revisions_x": "" 
}

/policy/update/- werkt een beleid bij met de opgegeven parameters:

NaamVerplicht*Info
idjaid van het beleid dat je bijwerkt op dit moment komt dit direct overeen met een bedrijfs-id
space_quotaneemoet een geheel getal zijn
max_file_sizeneemoet een geheel getal zijn
purge_deletedneemoet 'true' of 'false' zijn als je het meegeeft
trim_revisionsneemoet 'true' of 'false' zijn als je het meegeeft
excluded_extensionsneedoor komma's gescheiden lijst van bestandsextensies, bijv.: ".mp3,.ogg,*.avi"
user_purge_deletedneemoet 'true' of 'false' zijn als je het meegeeft
purge_deleted_frequencyneegeheel getal voor hoe vaak verwijderde bestanden worden opgeschoond
user_trim_revisionsneemoet 'true' of 'false' zijn als je het meegeeft
user_create_backupsneemoet 'true' of 'false' zijn als je het meegeeft
trim_revisions_xneegeheel getal als grens voor het inkorten van revisies

Root

/root// - haalt de root met het opgegeven id op

voorbeeldantwoord:

{
    "id": 1,
    "name": "Files",
    "description": "",
    "company_id": 2,
    "person_id": 1,
    "dept_share": false,
    "backup": false
}

/root/create/- maakt een nieuwe root aan met de opgegeven parameters:

NaamVerplichtInfo
company_idjabedrijfs-id voor de nieuwe root
namejanaam van de nieuwe root
person_idneeoptioneel persoons-id voor de root
defaultneetrue of false om de nieuwe root de standaardroot van de opgegeven persoon te maken
descriptionneeoptionele beschrijving van de nieuwe root
dept_shareneetrue of false om de nieuwe root een teamshare te maken

/root/update/- werkt een root bij met de opgegeven parameters:

NaamVerplichtInfo
idjaid van de root die je bijwerkt
company_idneebedrijfs-id voor de root
nameneenaam van de root
descriptionneebeschrijving van de root
person_idneepersoon die eigenaar wordt van de root
defaultneetrue of false om de root de standaardroot van de persoon te maken

Geïmplementeerde endpoints

/machine// - haalt de machine met het opgegeven id op

voorbeeldantwoord:

don't have any machines locally for testing...

/machine/update/- werkt een machine bij met de opgegeven parameters:

NaamVerplichtInfo
idjaid van de machine die je bijwerkt
bandwidth_throttleneegeheel getal voor de bandbreedtebeperking
throttle_exception_downeemoet een leesbare lijst van gehele getallen zijn voor de dagen van de week, met 0=maandag, 6=zondag. Voorbeeld: [0,1,2,3]
throttle_exception_daysneemoet, als je het meegeeft, 'weekdays' of 'weekends' zijn; dat zet throttle_exception_dow op respectievelijk [0,1,2,3,4] of [5,6] en overschrijft elke waarde die je voor throttle_exception_dow meestuurt
throttle_exception_startneetijdwaarde in de vorm 'HH:mm' of 'HH:mm:ss'
throttle_exception_endneetijdwaarde in de vorm 'HH:mm' of 'HH:mm:ss'
throttle_exception_throttleneegeheel getal voor de uitzonderingswaarde van de beperking

Organisaties

/organization// - haalt de organisatie met het opgegeven id op

voorbeeldantwoord:

{
    "id": 2,
    "parent_id": 1,
    "name": "Default Organization",
    "slug": "default-organization",
    "description": "",
    "email": "demouser@vboxx.nl",
    "hostname": "localhost",
    "policy": "{ .... }",
    "created": "2012-10-04T16:35:04.701000-06:00",
    "email_server_id": null,
    "psa": null,
    "bandwidth_throttle": null,
    "throttle_exception_days": null,
    "throttle_exception_start": null,
    "throttle_exception_end": null,
    "throttle_exception_throttle": null,
    "throttled": false,
    "active": true,
    "throttle_exception_dow": null
}

/organization//organizations/ - haalt de organisaties onder de organisatie met het opgegeven id op. De resultaten komen per 10 terug

/organization//organizations/page// - haalt pagina page_num met 10 resultaten op

voorbeeldantwoord:

{
    "total_pages": 1,
    "page": 1,
    "total_organizations": 3,
    "organizations": [
        {
            "id": 2,
            "parent_id": 1,
            "name": "Default Organization",
            "slug": "default-organization",
            "description": "",
            "email": "demouser@vboxx.nl",
            "hostname": "localhost",
            ....
        },
        {....}
}

/organization//roots/ - haalt de roots onder de organisatie met het opgegeven id op

/organization//roots/page// - haalt pagina page_num met 10 resultaten op

voorbeeldantwoord:

{
    "total_roots": 16,
    "total_pages": 2,
    "page": 1,
    "roots": [
        {
            "company_id": 2,
            "company_name": "Default Organization",
            "root_id": 16,
            "name": "api_updated",
            "physical_space": 0,
            "file_count": 0,
            "revision_count": 0,
            "created": "2012-10-18T15:38:24.293000-06:00",
            "dept_share": false,
            "backup": false,
            "person_id": null,
            "first_name": null,
            "last_name": null,
            "username": null,
            "email": null
        },
        { .... }
    ]
}

/organization//machines/ - haalt de machines onder de organisatie met het opgegeven id op

/organization//machines/page// - haalt pagina page_num met 10 resultaten op

voorbeeldantwoord: geen machines om lokaal mee te testen

/organization//persons/ - haalt de personen onder de organisatie met het opgegeven id op

/organization//persons/page// - haalt pagina page_num met 10 resultaten op

voorbeeldantwoord:

{
    "total_persons": 30,
    "total_pages": 3,
    "page": 1,
    "persons": [
        {
            "id": 31,
            "first_name": "Louis",
            "last_name": "API",
            "email": "demouser2@vboxx.nl",
            "use_ldap": false,
            "username": "" 
        },
        { .... }
    ]
}

/organization/create/- maakt een organisatie aan met de volgende parameters:

NaamVerplichtInfo
namejanaam van de nieuwe organisatie
hostnameneestandaard een lege string
descriptionneestandaard een lege string
contact_emailjacontact-e-mailadres van de organisatie
slugjaslug van de organisatie
policyjabeleid van de organisatie
parent_idjaid van de bovenliggende organisatie
bandwidth_throttleneegeheel getal voor de bandbreedtebeperking
throttle_exception_downeemoet een leesbare lijst van gehele getallen zijn voor de dagen van de week, met 0=maandag, 6=zondag. Voorbeeld: [0,1,2,3]
throttle_exception_daysneemoet, als je het meegeeft, 'weekdays' of 'weekends' zijn; dat zet throttle_exception_dow op respectievelijk [0,1,2,3,4] of [5,6] en overschrijft elke waarde die je voor throttle_exception_dow meestuurt
throttle_exception_startneetijdwaarde in de vorm 'HH:mm' of 'HH:mm:ss'
throttle_exception_endneetijdwaarde in de vorm 'HH:mm' of 'HH:mm:ss'
throttle_exception_throttleneegeheel getal voor de uitzonderingswaarde van de beperking

/organization/update/- werkt een organisatie bij met de volgende parameters:

NaamVerplichtInfo
idjaid van de organisatie die je bijwerkt
nameneenieuwe naam van de organisatie, moet uniek zijn in het systeem
descriptionneenieuwe beschrijving van de organisatie
contact_emailneenieuw e-mailadres van de organisatie
slugneenieuwe slug van de organisatie, moet uniek zijn in het systeem
policyneenieuw beleid van de organisatie

Functies voor deellinks

• Basis-URL voor delen: https:///1/sharelink/1/ name>/?&session_token=

• Parameters:

o download_notify = 0 or 1 --> bepaalt of de maker van de deellink een melding krijgt als het gedeelde bestand wordt gedownload: 1 geeft een melding, 0 niet; standaard is 0

o download_limit = --> bepaalt hoe vaak een bestand kan worden gedownload: standaard onbeperkt

o subscribers = door komma's gescheiden lijst van e-mailadressen --> bepaalt de ontvangers van de deellink, die alleen-lezen toegang krijgen: standaard geen

o expires = datum in de vorm YYYY-MM-DD --> bepaalt de vervaldatum van de deellink: standaard geen

Voorbeeld van een volledige URL

http://localhost/1/sharelink/1/folderName/documentName.txt?download_notify=1&download_limit=5&subscribers=demouser1@vboxx.nl,demouser2@vboxx.nl,demouser3@vboxx.nl&download_limit=2&expires=2013-11-01&session_token=5a5aHqVz2AkiLTBF9whrAw7wwKIjPUHRwOXPbpxvpmZaINyrjcaU2NDBUjsFSuEo7MvENkJyh6Ajvgh95tyNtpqo5l98kJG0m7Ddlxv24AWRJWV7sJ3OlfACpD8hIze4

Een gebruiker via de API op een teamshare abonneren

Volledige URL: https://mysite.com/1/management/root/subscribe/?session_token=some_token

Dit is een POST-verzoek met de volgende formuliervariabelen:

• root_id van de teamshare

• person_id van de gebruiker die je abonneert

Let op: Dit commando abonneert alleen via het web op de teamshare; abonnementen per machine worden op dit moment niet ondersteund.

Kom je er niet uit?

Ons supportteam in Nederland helpt je per e-mail en telefoon.