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])

• Applications
• Users
• Objects
• Transactions
• Batch

© 2024 Bitground Software