Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time
119 lines (86 sloc) 3.68 KB

General API guidelines

State: first version, this document will improve.

For concrete list and description of resources and methods visit the Workonomic API explorer. You will need and API token for that.

A basic call

We use curl for examples, so you can try them for yourself. Here we call resource "project" with method "select-all". We get the JSON with data back, which is default format. API token is passed as HTTP BASIC AUTH user parameter.

$ curl -v -k \
  -u pdabm35106fnc7kzy7uatv9rdasdsadasdasde:x \
  -d "" \

>> [[{"id":14,"shortname":"abel","name":"","id_client":16,"special":0,"qtymu":null,

Passing arguments

You can also notice we defined a method argument here (id=18). We must send arguments over as regular x-www-form-urlencoded POST values. All API requests must be POST calls.

$ curl -v -k \
  -u pdabm35106fnc7kzy7uatv9rd5rgasdasdsadasd:x \
  -d "id=18" \

>> id;shortname;name;id_client;special;qtymu;qlylabels;deftime;color;billable

Output formats

By default API returns JSON as in first example, but you can look at the second example where we defined csv output. But we can define a format, in this case csv (comma separated values).

  • json - JSON
  • csv - comma separated values
  • rmap - rebol map
  • tsv - tab separated values (todo)
  • xml - XML (todo)

Stacking methods

We can stack multiple methods. They are called sequentiall and the result of the last one is returned.

$ curl -v -k \
  -u pdabm35106fnc7kzy7uatv9rd5rgasdasdsadasd:x \
  -d "id=18" \

>> id;shortname;name;id_client;special;qtymu;qlylabels;deftime;color;billable

Explore mode

You enter explore mode by setting the _x flag.

Explore mode can be invoked:

  • withouth resource or method defined: in this case it retuns the list of resoures
  • with just resource defined: returns the list and descriptions of methods
  • with resource and method: retuns the list of arguments
$ curl -v -k \
  -u pdabm35106fnc7kzy7uatv9rd5rga32jchet208e:x \
  -d "" \

>> [[{"name":"insert-into","description":"Inserts item into the table and returns the last id."},
	{"name":"insert-select","description":"Insert item into the table and returns the unit as stored in the table."},
	{"name":"update","description":"Updates item with given ID with given values."},

Let's recap

  • all calls must be HTTP POST
  • pass API token as HTTP BASIC AUTH username (when out of alpha will run over HTTPS!)
  • define resource and method with _r and _m
  • optionally define output format with _f
  • use _x for explore mode (returns information about the current level)
  • form-urlencode arguments and send them as POST data
  • you can stack multiple method calls inside one HTTP call and the result of the last will get returned

Error statuses

  • 400 - no resource given
  • 400 - no method given
  • 401 - wrong api token
  • 403 - validation error (returned data shows the error, for example: ["validation",{"id":"required"}] )
  • 404 - resource or method not found
  • 500 - internal server error