zkBox API
In this page is presented the interface of the zkBox server API.
Below there are some general rules applicable when making API calls and then are listed all the
method accepted by the server along with a short description for each.
For clarity there are also examples given for each method with sample input parameters and
possible returned response.
General rules
The REST endpoint of the zkBox API is located here: https://api.zkbox.com/rest.
This means that everywhere below in the API reference where you'll see something like:
GET object/A6HNCRFZMDMMC4VW
it will actually refer to:
GET https://api.zkbox.com/object/A6HNCRFZMDMMC4VW
The web service is mainly following the REST principles, but not 100%. There are cases where
you'll see that these rules are not exactly followed, sometimes for simplicity, sometimes
because it wasn't possible to model that part on the REST philosophy.
Making calls
When making a call (i.e. making a POST, GET, PUT or DELETE) to a zkBox method you have to
provide one of the following headers:
The "X-zkBox-Auth" header
This header should be provided if the call is not referring to a user, but if it's application specific.
The header should be set at the application level because the header it's containing the
signature for this specific call on behalf of the accessing application.
In this category there are only the functions from the Applications group
and some from the Users group (the ones related to the authentication).
All the other functions are falling into the second category, the user-specific functions and
the next header should be provided.
Example: X-zkBox-Auth=0100YUJ44LK4M989O0EW20100205123129B558ED[...]
The "X-zkBox-UserAuth" header
This header should be provided for the rest of the functions that are not falling into the
category above, which represents the most of the zkBox methods.
The header should be provided as an HTTP header, but there is also the possibility to provide it
in the "Cookie" header (to be able to send it from a browser).
This header contains the signature of the call on behalf of the user (signed on the client by
the user with its session key) and the signature of the application that it's making the call
on behalf of the user (signed on the server by the zkBox proxy).
Example: X-zkBox-UserAuth=N90XV5A40T33CQIG3DWJJ7X9IUK1P9CCVL6FC418[...]
When using any of the client libraries these
headers are set auto-magically for you.
Receiving responses
For any call made to the server, there are always two headers returned:
The "X-zkBox-Runtime" header
This is the running time of the operation on the server.
It's represented in milliseconds and it's the time spent in the zkBox server from the moment
your call hit the zkBox servers until the moment the response is sent back (so not including
the network times to and from the server).
Example: X-zkBox-Runtime=147ms
The "X-zkBox-Reference" header
This header contains an identifier that it's unique for each call and can be used to diagnose
and troubleshoot potential problems.
If you think that you made an API call that it's not behaving as designed, providing us with
this identifier will speed up troubleshooting the potential issue.
Example: X-zkBox-Reference=ZKBOX-API-046321-LIVE-IP-1EDC86B6-025644[...]
If an operation was successfully sent and executed by the server and if there were no logical errors
(e.g. you tried to delete an object by a given Id and that Id was a valid one) then you'll get
a "200 OK" HTTP response header and, in the response you'll get additional data, if it was requested.
The response will include the logical error code, which in this case it will be 0;
so you'll receive something like this:
Example: { error: 0, message: "Success", data: { [additional response data goes here] } }
If the operation was executed, but a logical error occurred (e.g. you tried to delete an object,
but the Id doesn't exists anymore) you'll still get a "200 OK" HTTP response (yeap, not exactly
following the REST guidelines here), but in the response body you'll get the logical error:
Example: { error: 104, message: "The object does not exist" }
At the moment of a call if there is any issue with the authentication (the "X-zkBox-Auth"
or the "X-zkBox-UserAuth" header) you'll get a "400" HTTP error:
Example: 400 User not authenticated
If there is an issue with the parameters passed when making a call (e.g. when asking for get an
object by its identifier, you're not providing an identifier which doesn't have 16 characters
in length, but a different size) you'll also get a "400" HTTP error:
Example: for the request GET objects/123456789012345 you'll get the response
400 User not authenticated
because the objectId provided at the moment of the call (the string "123456789012345") is not
a valid identifier in zkBox
(a valid identifier contains 16 characters from the following alphabet [0-9A-Z])
Get application info
Returns the details of the calling application. This method is callable by a zkBox application and not by a zkBox user.
GET application/info
200 OK
{
error: 0,
data:
{
objectsCount: "43989",
usersCount: "2983"
}
}
400 Not authenticated
500 Internal server error
Check user
Check if an user exists in the system.
PUT user/check
{
login: "3EB954E6D1CBC2340631C5F48B24EF0A977CD337[...]"
}
200 OK
{
error: 0,
data:
{
exists: "true"
}
}
400 Not authenticated
500 Internal server error
Add user
Add an user to the system.
POST user
{
login: "3EB954E6D1CBC2340631C5F48B24EF0A977CD337[...]",
s: "7741AD53195FDE13B4B2BB11077274E4E9905F67[...]",
v: "A13A423562218889B6FFF19BA8AFCC0E5F26EECE[...]"
}
200 OK
{
error: 0,
data: {}
}
200 OK
{
error: 100,
message: "The user already exists"
}
400 Not authenticated
500 Internal server error
Authenticate an user - step 1
This is the first step for authenticating an user into the system.
PUT user/auth/step1
{
A: "7230DF14D7E85E0CC52DCA896DC11E61648A1F96[...]",
login: "3EB954E6D1CBC2340631C5F48B24EF0A977CD337[...]"
}
200 OK
{
error: 0,
data:
{
uniq: "DSMEDGRE9Y6U1N3W",
s: "7741AD53195FDE13B4B2BB11077274E4E9905F67[...]",
B: "3623110F4F78918915E68D1D92DBD614860CFFB9[...]",
u: "EE37104AFA80550D65353F177296F45B3DA40FAC[...]"
}
}
200 OK
{
error: 101,
message: "Invalid username or password"
}
400 Not authenticated
500 Internal server error
Authenticate an user - step 2
This is the second step for authenticating an user into the system.
PUT user/auth/step2
{
uniq: "DSMEDGRE9Y6U1N3W",
login: "3EB954E6D1CBC2340631C5F48B24EF0A977CD337[...]",
m1: "693C14A26A7362C2830034D12576FE25D1A95719[...]"
}
200 OK
{
error: 0,
data:
{
userId: "XNQ05BGSKI8DJYZ1",
userVersion: "9U5O2TX9Z53X3UQI",
sessionId: "NR2DPJBJQ1DXD59ATZBYGJXFHGKJ8URUHJ41885X[...]",
m2: "7AB0C32455DB6161AF5990EED3B238E0256A134D[...]"
}
}
200 OK
{
error: 101,
message: "Invalid username or password"
}
400 Not authenticated
500 Internal server error
Begin updating an user
This method should be called before starting to update an user.
POST user/update
{
s: "7741AD53195FDE13B4B2BB11077274E4E9905F67[...]",
v: "A13A423562218889B6FFF19BA8AFCC0E5F26EECE[...]"
}
200 OK
{
error: 0,
data:
{
newUserVersion: "S9X4430MI1UEYVYU"
}
}
200 OK
{
error: 101,
message: "Invalid username or password"
}
400 Not authenticated
500 Internal server error
Set object
This method is part of the user updated procedure and it's storing a new version object, the one encrypted with the new encryption key.
PUT user/update/S9X4430MI1UEYVYU/object/A6HNCRFZMDMMC4VW
{
type: "notes",
data: "U2FsdGVkX18EBQYHAAECA7VOPk63Te+RMnHu8Baf[...]"
}
200 OK
{
error: 0,
data: {}
}
400 Not authenticated
500 Internal server error
Finish updating an user
This method should be called to complete an user update operation.
PUT user/update/S9X4430MI1UEYVYU
{}
200 OK
{
error: 0,
data: {}
}
200 OK
{
error: 101,
message: "Invalid username or password"
}
400 Not authenticated
500 Internal server error
Abort updating an user
This method should be called to abort an user update operation.
DELETE user/update/S9X4430MI1UEYVYU
200 OK
{
error: 0,
data: {}
}
200 OK
{
error: 101,
message: "Invalid username or password"
}
400 Not authenticated
500 Internal server error
Logout user
Logout the calling user from the system.
PUT user/logout
{}
200 OK
{
error: 0,
data: {}
}
200 OK
{
error: 101,
message: "Invalid username or password"
}
400 Not authenticated
500 Internal server error
Delete an user
Delete the calling user from the system.
DELETE user
200 OK
{
error: 0,
data: {}
}
200 OK
{
error: 101,
message: "Invalid username or password"
}
400 Not authenticated
500 Internal server error
Add object
This method is adding an object to the system.
POST object
{
data: "U2FsdGVkX18EBQYHAAECA7VOPk63Te+RMnHu8Baf[...]"
}
200 OK
{
error: 0,
data:
{
objectId: "A6HNCRFZMDMMC4VW"
}
}
400 Invalid arguments
400 Not authenticated
500 Internal server error
Add object with type
This method is adding to the system an object of a given type.
POST object/type/notes
{
data: "U2FsdGVkX18EBQYHAAECA7VOPk63Te+RMnHu8Baf[...]"
}
200 OK
{
error: 0,
data:
{
objectId: "A6HNCRFZMDMMC4VW"
}
}
400 Invalid arguments
400 Not authenticated
500 Internal server error
Add object in transaction
This method is adding within a transaction an object to the system.
POST transaction/93VBBRTOK5DR1ZR4/object
{
data: "U2FsdGVkX18EBQYHAAECA7VOPk63Te+RMnHu8Baf[...]"
}
200 OK
{
error: 0,
data:
{
objectId: "A6HNCRFZMDMMC4VW"
}
}
200 OK
{
error: 150,
message: "Invalid transaction id"
}
400 Invalid arguments
400 Not authenticated
500 Internal server error
Add object with type in transaction
This method is adding to the system an object of a given type while running in a transaction.
POST transaction/93VBBRTOK5DR1ZR4/object/type/notes
{
data: "U2FsdGVkX18EBQYHAAECA7VOPk63Te+RMnHu8Baf[...]"
}
200 OK
{
error: 0,
data:
{
objectId: "A6HNCRFZMDMMC4VW"
}
}
200 OK
{
error: 150,
message: "Invalid transaction id"
}
400 Invalid arguments
400 Not authenticated
500 Internal server error
Get object
This method is retrieving an object by its identifier.
GET object/A6HNCRFZMDMMC4VW
200 OK
{
error: 0,
data:
{
objectId: "A6HNCRFZMDMMC4VW",
type: "notes",
data: "U2FsdGVkX18EBQYHAAECA7VOPk63Te+RMnHu8Baf[...]"
}
}
200 OK
{
error: 104,
message: "The object does not exist"
}
400 Invalid arguments
400 Not authenticated
500 Internal server error
Update object
This method is updating an existing object.
PUT object/A6HNCRFZMDMMC4VW
{
data: "U2FsdGVkX18EBQYHAAECA7VOPk63Te+RMnHu8Baf[...]"
}
200 OK
{
error: 0,
data: {}
}
200 OK
{
error: 104,
message: "The object does not exist"
}
400 Invalid arguments
400 Not authenticated
500 Internal server error
Update object in transaction
This method is updating an existing object while in a transaction.
PUT transaction/93VBBRTOK5DR1ZR4/object/A6HNCRFZMDMMC4VW
{
data: "U2FsdGVkX18EBQYHAAECA7VOPk63Te+RMnHu8Baf[...]"
}
200 OK
{
error: 0,
data: {}
}
200 OK
{
error: 104,
message: "The object does not exist"
}
200 OK
{
error: 150,
message: "Invalid transaction id"
}
400 Invalid arguments
400 Not authenticated
500 Internal server error
Delete object
This method is deleting an existing object.
DELETE object/A6HNCRFZMDMMC4VW
200 OK
{
error: 0,
data:
{
type: "notes"
}
}
200 OK
{
error: 104,
message: "The object does not exist"
}
400 Invalid arguments
400 Not authenticated
500 Internal server error
Delete object in transaction
This method is deleting an existing object while in a transaction.
DELETE transactionId/93VBBRTOK5DR1ZR4/object/A6HNCRFZMDMMC4VW
200 OK
{
error: 0,
data:
{
type: "notes"
}
}
200 OK
{
error: 104,
message: "The object does not exist"
}
200 OK
{
error: 150,
message: "Invalid transaction id"
}
400 Invalid arguments
400 Not authenticated
500 Internal server error
Get all objects
This method is retrieving all objects belonging to the calling user.
GET objects
200 OK
{
error: 0,
data:
{
objects:
[
{
objectId: "FIR8JUFUO3Q1YFSQ",
type: "account-preferences",
data: "U2FsdGVkX18EBQYHAAECAyVnMdY3JZboDpA1bLJV[...]"
},
{
objectId: "5FAUHANNFAI6NKD0",
type: "notes",
data: "U2FsdGVkX18EBQYHAAECA3SZLu94hwHka1vdDF1C[...]"
},
{
objectId: "1F61E43WJGPQBLR2",
type: "comments",
data: "U2FsdGVkX18EBQYHAAECA/PVR+J91IkmqNdHBapN[...]"
},
{
objectId: "A6HNCRFZMDMMC4VW",
type: "notes",
data: "U2FsdGVkX18EBQYHAAECA7VOPk63Te+RMnHu8Baf[...]"
},
...
]
}
}
400 Invalid arguments
400 Not authenticated
500 Internal server error
Get a list of objects by IDs
This method is retrieving a list of objects specified by their identifiers.
PUT objects/list
[
"FIR8JUFUO3Q1YFSQ",
"A6HNCRFZMDMMC4VW",
...
]
200 OK
{
error: 0,
data:
{
objects:
[
{
objectId: "FIR8JUFUO3Q1YFSQ",
type: "account-preferences",
data: "U2FsdGVkX18EBQYHAAECAyVnMdY3JZboDpA1bLJV[...]"
},
{
objectId: "A6HNCRFZMDMMC4VW",
type: "notes",
data: "U2FsdGVkX18EBQYHAAECA7VOPk63Te+RMnHu8Baf[...]"
},
...
]
}
}
400 Invalid arguments
400 Not authenticated
500 Internal server error
Get all objects of a given type
This method is retrieving all objects of a given type.
GET objects/type/notes
200 OK
{
error: 0,
data:
{
objects:
[
{
objectId: "5FAUHANNFAI6NKD0",
type: "notes",
data: "U2FsdGVkX18EBQYHAAECA3SZLu94hwHka1vdDF1C[...]"
},
{
objectId: "A6HNCRFZMDMMC4VW",
type: "notes",
data: "U2FsdGVkX18EBQYHAAECA7VOPk63Te+RMnHu8Baf[...]"
},
...
]
}
}
400 Invalid arguments
400 Not authenticated
500 Internal server error
Get all objects IDs
This method is retrieving the identifiers of all the objects belonging to the calling user.
GET objects/ids
200 OK
{
error: 0,
data:
{
objectsIDs:
[
"FIR8JUFUO3Q1YFSQ",
"5FAUHANNFAI6NKD0",
"1F61E43WJGPQBLR2",
"A6HNCRFZMDMMC4VW",
...
]
}
}
400 Not authenticated
500 Internal server error
Get all objects ids by a given type
This method is retrieving the identifiers of all the objects of a given type belonging to the calling user.
GET objects/ids/type/notes
200 OK
{
error: 0,
data:
{
objectsIDs:
[
"5FAUHANNFAI6NKD0",
"A6HNCRFZMDMMC4VW",
...
]
}
}
400 Invalid arguments
400 Not authenticated
500 Internal server error
Begin a new transaction
This method is starting a new transaction.
POST transaction
{}
200 OK
{
error: 0,
data:
{
transactionId: "93VBBRTOK5DR1ZR4"
}
}
400 Not authenticated
500 Internal server error
Commit transaction
This method is committing and existing transaction.
PUT transaction/93VBBRTOK5DR1ZR4
{}
200 OK
{
error: 0,
data: {}
}
200 OK
{
error: 150,
message: "Invalid transaction id"
}
400 Invalid arguments
400 Not authenticated
500 Internal server error
Rollback transaction
This method is aborting an existing transaction.
DELETE transaction/93VBBRTOK5DR1ZR4
200 OK
{
error: 0,
data: {}
}
200 OK
{
error: 150,
message: "Invalid transaction id"
}
400 Invalid arguments
400 Not authenticated
500 Internal server error
Execute a batch operation
This method is executing multiple operations in a batch.
PUT batch
{
transactionId: "null",
stopOnFirstError: "true",
atStartBeginTransaction: "true",
atEndCommitTransaction: "true",
onErrorRollbackTransaction: "true",
operations:
[
{
operation: "UpdateObject",
objectId: "A6HNCRFZMDMMC4VW",
data: "U2FsdGVkX18EBQYHAAECA7VOPk63Te+RMnHu8Baf[...]"
},
{
operation: "AddObject",
type: "notes",
data: "U2FsdGVkX18EBQYHAAECA25T/nbc2dkWGNSYlGmN[...]"
}
]
}
200 OK
{
error: 0,
data:
{
results:
[
{
error: 0
data: {}
},
{
error: 0
data:
{
objectId: "8L7ICQS3E8JQNR69"
}
}
]
}
}
200 OK
{
error: 150,
message: "Invalid transaction id"
}
400 Invalid arguments
400 Not authenticated
500 Internal server error