Zimki Documentation

zimki.session

undefined — 2006-06-26T16:47:33.627+00:00

Provides access to properties and methods about the current Zimki session. Zimki Session objects are also Persistable.

The session can be used to store data between requests made from the same browser:

  zimki.session.fish = "trout";
  zimki.session.save();

The session will be restored automatically on the next request from that web browser (based on the cookie that it sends)

  var seafood = zimki.session.fish;

zimki.session.user

undefined — 2007-04-05T19:44:29.208+00:00

The zimki_user object of the user (if any) currently logged into the session. Can be set using zimki.session.login.

zimki.session.login

undefined — 2006-06-26T16:51:06.706+00:00

Logs a session in. Requires a valid username and password for the current realm. If the username and password combination is invalid an error is thrown.

Example:

function login ( args ) {
  try {
    zimki.session.login( args.username, args.password );
  }
  catch (e) {
    return "could not log in";
  }
  return "logged in";
}
zimki.publishPath( '/login', login );

XML API

[object Object] — 2006-09-20T13:28:51.592+00:00

Moved to ZimkiExternalAPI

zimki

undefined — 2006-06-23T16:36:29.161+00:00

For those new to Zimki, check out the Zimki CookBook. Find out how to set up your realms and use the various functions within Zimki. The Zimki documentation will continue to improve over the coming weeks and months.

The 'zimki' variable contains most of the zimki-specific parts of the zimki server platform.

Classes

File

undefined — 2006-06-27T16:51:59.638+00:00

File represents a file in the Zimki file store.

Many of the properties of the file objects are changable, but you must call save() afterwards, similarly to the persistency engine. Prior to Zimki 1.10 you could not set arbitrary properties on them, but as of 1.10 we have lifted this restriction; files are now full-blown first class citizens, and every file is actually a 'zimki_file' instance.

Files can be added to your domain via the Portal interface, or by accepting file uploads using a server-side JavaScript method. You can also create them from JavaScript.

The publish and unpublish methods can be used to add/remove publication paths corresponding to the file.

ExternalAPI

undefined — 2007-03-16T16:38:00.763+00:00

Overview

Zimki has an external RESTian API that currently supports 2 response types - XML and standards-compliant JSON.

The API is broken down into two sections:

Zimki External API

The Zimki External API is an extensible API that allows customers and their users to access core services available in a realm such as user authentication, session management, manipulating instances and files, creating Captchas, and more.

Default API Endpoint:

Customer External API

The Customer External API is an authenticated API that allows customers to manipulate their realms, updating instances, setting API keys, looking at billing data, and more.

Default API Endpoint:

https://www.zimki.com/api

Setting the Response Type

To choose a response type you need to pass in a _type parameter to the request:

http://docs.realm.zimki.com/zimki?method=zimki.session.create&_type=json {"data":{"salt":"63305","group":[],"id":"741d88ee-d6d9-11db-b1dc-92c77c5d54ec","expires":"2007-03-20T12:52:18.290+00:00"},"stat":"ok"}

XML is the default response type. An unrecognized _type will default to XML.

ZimkiExternalAPI

undefined — 2007-03-16T16:11:25.454+00:00

zimki.captcha.create

Generate a CAPTCHA image for the currently logged in user. The image will be stored in the local file repository, and published using zimki publication calls, so will count towards any quota you have. The url returned is the url under which the captcha will be available.

arguments

name

type

description

required

Example response

<?xml version="1.0" encoding="utf-8"?>
<rsp stat="ok">
  <captcha url="/relative/url/to/capcha/UUID.png" 
           id="0508B9CF-12BB-4C2C-9DB7-E45A03755501" expires="date"/>
</rsp>

zimki.captcha.verify

Verify that a captcha is correct. Pass the ID of the generated captca, and the code that you are guessing. Will return an error if the guess fails, or an empty response if the guess succeeds.

arguments

name	type	description	required
captcha_id	text	The ID of the captcha to verify	required
code	text	The code to verify	required

Example response

empty response

zimki.file.create

Upload a file into zimki. This won't make the file visible to the outside world, however - you'll need to explicitly publish it to achieve that. Uploaded files will be owned by the user that uploaded them, and by default will only be editable and publishable by that user.

The description field is the only human-readable way you will be able to identify this file after upload, other than remembering the ID returned from this method. It will default to the filename of the upload, but you can set it if you prefer something else.

This method takes implicit and required apikey and sessionid parameters.

arguments

name	type	description	required
description	text	A human-readable text description for the file.	optional
group_id	text	the group_id to give to the file, defaults to the current user's first group	optional
mimetype	text	Set if you want to force the mimetype of the uploaded file to something in particular	optional
permissions	text	the permissions to give to the file. Defaults to 0xFF0101	optional
upload	multipart	The file to upload, as an HTTP upload	required

Example response

<?xml version="1.0" encoding="utf-8"?>
<rsp stat="ok">
  <file permissions="0x765" owner_id="owner"
        mimetype="image/jpeg" id="0F4E8148-107F-408C-972B-D2451600A553" 
        group_id="group" filesize="1234" expires="2005-04-01T12:00"
        created="2004-05-01T12:00">
    <description>a description of the file.</description>
    <location url="/some/publish/url" created="2004-05-10T12:00"/>
    <location url="/some/publish/url" created="2004-05-10T12:00"/>
  </file>
</rsp>

zimki.file.delete

Delete an uploaded file. Only root and users with the 'delete' ability on a file can do this - by default this is only the owner of the file.

This method takes implicit and required apikey and sessionid parameters.

arguments

name	type	description	required
file_id	text	the ID of the file to delete	required

Example response

empty response

zimki.file.search

Lists the files uploaded. If you are logged in as root, it will list all files on the system, otherwise it will list only files that have been uploaded by the currently logged-in user.

This method takes implicit and required apikey and sessionid parameters.

arguments

name	type	description	required
page	text		optional
per_page	text		optional

Example response

<?xml version="1.0" encoding="utf-8"?>
<rsp stat="ok">
  <resultset per_page="2" pages="4" page="1">
    <file permissions="0x765" owner_id="owner" mimetype="image/jpeg" 
          id="0F4E8148-107F-408C-972B-D2451600A553" group_id="group"
          filesize="1234" expires="2005-04-01T12:00"
          created="2004-05-01T12:00">
      <description>a description of the file.</description>
      <location url="/some/publish/url" created="2004-05-10T12:00"/>
      <location url="/some/publish/url" created="2004-05-10T12:00"/>
    </file>
    <file permissions="0x765" owner_id="owner" mimetype="image/jpeg" 
          id="0F4E8148-107F-408C-972B-D2451600A553" group_id="group"
          filesize="1234" expires="2005-04-01T12:00"
          created="2004-05-01T12:00">
      <description/>
      <location created="2004-05-01T12:00"/>
      <location>a description of the file.</location>
    </file>
  </resultset>
</rsp>

zimki.file.unpublish

Unpublish a file - it will no longer be available from the passed url, assuming it was to begin with. Only a file's owner, and root users, can do this.

This method takes implicit and required apikey and sessionid parameters.

arguments

name	type	description	required
file_id	text	the id of the file to unpublish	required
url	text	if given, should be the url of the publication you want to remove. Otherwise removes all publications.	optional

Example response

<?xml version="1.0" encoding="utf-8"?>
<rsp stat="ok">
  <file permissions="0x765" owner_id="owner" mimetype="image/jpeg" 
        id="0F4E8148-107F-408C-972B-D2451600A553" group_id="group"
        filesize="1234" expires="2005-04-01T12:00"
        created="2004-05-01T12:00">
    <description>a description of the file.</description>
    <location url="/some/publish/url" created="2004-05-10T12:00"/>
    <location url="/some/publish/url" created="2004-05-10T12:00"/>
  </file>
</rsp>

zimki.file.update

Change the description, group, or permissions of an already-upload file. Only root or the file's owner can change these properties.

This method takes implicit and required apikey and sessionid parameters.

arguments

name	type	description	required
description	text	the new description for the file	optional
file_id	text	the id of the file to update	required
group_id	text	the new group_id of the file	optional
mimetype	text	Set if you want to force the mimetype of the uploaded file to something in particular	optional
permissions	text	the new permissions for the file	optional

Example response

<?xml version="1.0" encoding="utf-8"?>
<rsp stat="ok">
  <file permissions="0x765" owner_id="owner" mimetype="image/jpeg" 
        id="0F4E8148-107F-408C-972B-D2451600A553" group_id="group"
        filesize="1234" expires="2005-04-01T12:00"
        created="2004-05-01T12:00">
    <description>a description of the file.</description>
    <location url="/some/publish/url" created="2004-05-10T12:00"/>
    <location url="/some/publish/url" created="2004-05-10T12:00"/>
  </file>
</rsp>

zimki.instance.create

Creates an instance of a persisted class. Instances can have any number of keys with any (with some exceptions) names - a class provides no checking of types, etc, beyond the initial permissions of the instance. Instances have an owner, a group, and rights of that owner and group to it's properties.

Any arguments provided to the method beyond those listed below are used as the initial state of the object's attributes.

An object has a special attribute 'expires', which may be set here. After this time, the object will no longer be accessible to API calls.

This method takes implicit and required apikey and sessionid parameters.

arguments

name	type	description	required
class	trim	the name of the class you are creating an instance of	required
group_id	text	the group owner of the new instance	optional
permissions	text	the initial permissions of the object, assuming you are able to set them	optional

remaining arguments are passed to the method directly

Example response

<?xml version="1.0" encoding="utf-8"?>
<rsp stat="ok">
  <instance permissions="1248753" owner_id="foo" 
            id="5BAA65C6-AE60-4194-B075-0899B64E39DD"
            group_id="bar" class="classname">
    <attribute type="string" name="foo">fooo</attribute>
    <attribute type="string" name="bar">baaaar</attribute>
  </instance>
</rsp>

zimki.instance.delete

Delete an instance of a class

This method takes implicit and required apikey and sessionid parameters.

arguments

name	type	description	required
class	text	the class of the instance you want to delete	required
instance_id	text	the ID of the instance you wish to delete	required

Example response

empty response

zimki.instance.deleteAttributes

arguments

name	type	description	required
class	text	the class of the instance you want to change	required
delete	csv	the attributes to delete. Pass many times to delete many attributes	required
instance_id	text	the ID of the instance you wish to change	required

Example response

<?xml version="1.0" encoding="utf-8"?>
<rsp stat="ok">
  <instance permissions="1248753" owner_id="foo" 
            id="5BAA65C6-AE60-4194-B075-0899B64E39DD" group_id="bar"
            class="classname">
    <attribute type="string" name="foo">fooo</attribute>
    <attribute type="string" name="bar">baaaar</attribute>
  </instance>
</rsp>

zimki.instance.deleteWhere

arguments

name	type	description	required
class	trim		required

remaining arguments are passed to the method directly

Example response

<?xml version="1.0" encoding="utf-8"?>
<rsp stat="ok">
  <deleted>3</deleted>
</rsp>

zimki.instance.retrieve

Returns the instance of the given class and ID, as XML.

This method takes implicit and required apikey and sessionid parameters.

arguments

name	type	description	required
class	text	the class of the instance you want the details of	required
instance_id	text	the ID of the instance you want the details of	required

Example response

<?xml version="1.0" encoding="utf-8"?>
<rsp stat="ok">
  <instance permissions="1248753" owner_id="foo" 
            id="5BAA65C6-AE60-4194-B075-0899B64E39DD" group_id="bar"
            class="classname">
    <attribute type="string" name="foo">fooo</attribute>
    <attribute type="string" name="bar">baaaar</attribute>
  </instance>
</rsp>

zimki.instance.search

Find instances of a class. Arguments to this method beyond those listed below are interpreted as searches on the attributes of the persisted objects.

This method takes implicit and required apikey and sessionid parameters.

arguments

name	type	description	required
class	trim		required
page	text		optional
per_page	text		optional

remaining arguments are passed to the method directly

Example response

<?xml version="1.0" encoding="utf-8"?>
<rsp stat="ok">
  <resultset per_page="2" pages="4" page="1">
    <instance permissions="1248753" owner_id="foo" 
              id="5BAA65C6-AE60-4194-B075-0899B64E39DD" group_id="bar"
              class="classname">
      <attribute type="string" name="foo">fooo</attribute>
      <attribute type="string" name="bar">baaaar</attribute>
    </instance>
    <instance permissions="1248753" owner_id="foo" 
              id="5BAA65C6-AE60-4194-B075-0899B64E39DD" group_id="bar"
              class="classname">
      <attribute/>
      <attribute/>
    </instance>
  </resultset>
</rsp>

zimki.instance.update

Change the properties of an instance of a class. Currently, you can only add and set properties.

All arguments to this method beyond those listed below are set as properties of the object.

This method takes implicit and required apikey and sessionid parameters.

arguments

name	type	description	required
class	text	the class of the instance you want to change	required
group_id	text	the new group of the instance	optional
instance_id	text	the ID of the instance you wish to change	required
permissions	text	the new permissions of the instance	optional

remaining arguments are passed to the method directly

Example response

<?xml version="1.0" encoding="utf-8"?>
<rsp stat="ok">
  <instance permissions="1248753" owner_id="foo" 
            id="5BAA65C6-AE60-4194-B075-0899B64E39DD" group_id="bar"
            class="classname">
    <attribute type="string" name="foo">fooo</attribute>
    <attribute type="string" name="bar">baaaar</attribute>
  </instance>
</rsp>

zimki.session.create

Creates a new session. To log into zimki, you'll need salt, and salt lives in a session, so you'll need to create a session first.

arguments

name	type	description	required
api_key	text	the API key	required

Example response

<?xml version="1.0" encoding="utf-8"?>
<rsp stat="ok">
  <session id="12345">
    <expires>2005-10-05 16:02:38Z</expires>
    <group name="foo" id="8361EF97-3DBC-44DE-A33B-F6E99C3EFE7A"/>
    <group name="foo" id="8361EF97-3DBC-44DE-A33B-F6E99C3EFE7A"/>
    <salt>12345678</salt>
    <user username="foo" last_login="2005-01-34T12:00"
          id="2471880F-8B7C-428B-8590-343D00484096"
          created="2005-01-34T12:00"/>
    <username>foo</username>
  </session>
</rsp>

zimki.session.delete

This is as close as you'll get to a 'logout' call. It'll make the session you call it on invalid. Don't try to re-use the session_id after this call, it won't work.

arguments

name	type	description	required
api_key	text	the API key	required
session_id	text	The session id	required

Example response

empty response

zimki.session.login

This is the login method. You'll need to know your username, a shared secret, and the salt of your current session. The shared secret should be the md5sum of the utf-8 encoded version of your password. This means that you must have created a session before making this call.

The 'hash' parameter here should be

md5( salt + secret )

which is probably

md5( salt + md5( password ) )

As a user, you have an ID, can can be in one or more groups, the details of which are returned by this call. Groups can affect your permissions to verious objects.

arguments

name	type	description	required
api_key	text	the API key	required
hash	text	a hash of the session's salt and your shared secret	required
session_id	text	The session id	required
username	text	your user's username	required

Example response

<?xml version="1.0" encoding="utf-8"?>
<rsp stat="ok">
  <session id="12345">
    <expires>2005-10-05 16:02:38Z</expires>
    <group name="foo" id="8361EF97-3DBC-44DE-A33B-F6E99C3EFE7A"/>
    <group name="foo" id="8361EF97-3DBC-44DE-A33B-F6E99C3EFE7A"/>
    <salt>12345678</salt>
    <user username="foo" last_login="2005-01-34T12:00"
          id="2471880F-8B7C-428B-8590-343D00484096"
          created="2005-01-34T12:00"/>
    <username>foo</username>
  </session>
</rsp>

zimki.session.retrieve

If you have an existing session, but you're forgotten who you are, what groups you're in, or what your user_id or salt is, this method will remind you.

arguments

name	type	description	required
api_key	text	the API key	required
session_id	text	The session id	required

Example response

<?xml version="1.0" encoding="utf-8"?>
<rsp stat="ok">
  <session id="12345">
    <expires>2005-10-05 16:02:38Z</expires>
    <group name="foo" id="8361EF97-3DBC-44DE-A33B-F6E99C3EFE7A"/>
    <group name="foo" id="8361EF97-3DBC-44DE-A33B-F6E99C3EFE7A"/>
    <salt>12345678</salt>
    <user username="foo" last_login="2005-01-34T12:00"
          id="2471880F-8B7C-428B-8590-343D00484096"
          created="2005-01-34T12:00"/>
    <username>foo</username>
  </session>
</rsp>

zimki.user.retrieve

Returns the details of the currently logged in user.

This method takes implicit and required apikey and sessionid parameters. get a user's details

arguments

name

type

description

required

Example response

<?xml version="1.0" encoding="utf-8"?>
<rsp stat="ok">
  <user username="foo" last_login="2005-01-34T12:00" 
        id="2471880F-8B7C-428B-8590-343D00484096" created="2005-01-34T12:00">
    <group name="foo" id="8361EF97-3DBC-44DE-A33B-F6E99C3EFE7A"/>
    <group name="foo" id="8361EF97-3DBC-44DE-A33B-F6E99C3EFE7A"/>
  </user>
</rsp>

zimki.user.update

Update the logged-in user's details.

Changing your username will not log you out, and it will not change your user_id, but the old username will no longer work.

This method takes implicit and required apikey and sessionid parameters.

arguments

name	type	description	required
secret	text	the new secret	optional
username	text	the new requested username	optional

Example response

<?xml version="1.0" encoding="utf-8"?>
<rsp stat="ok">
  <user username="foo" last_login="2005-01-34T12:00" 
        id="2471880F-8B7C-428B-8590-343D00484096" created="2005-01-34T12:00">
    <group name="foo" id="8361EF97-3DBC-44DE-A33B-F6E99C3EFE7A"/>
    <group name="foo" id="8361EF97-3DBC-44DE-A33B-F6E99C3EFE7A"/>
  </user>
</rsp>

CustomerExternalAPI

undefined — 2007-03-16T16:38:08.005+00:00

customer.apikey.create
customer.apikey.update
customer.billing.chargesByDay
customer.billing.chargesByHour
customer.billing.pendingPurchases
customer.billing.purchases
customer.class.create
customer.class.delete
customer.class.search
customer.class.update
customer.file.create
customer.file.delete
customer.file.publish
customer.file.search
customer.file.unpublish
customer.file.update
customer.group.create
customer.group.delete
customer.group.retrieve
customer.group.search
customer.group.update
customer.instance.create
customer.instance.delete
customer.instance.deleteAttributes
customer.instance.deleteWhere
customer.instance.retrieve
customer.instance.search
customer.instance.update
customer.javascript.run
customer.realm.copy
customer.realm.create
customer.realm.delete
customer.realm.restore
customer.realm.retrieve
customer.realm.search
customer.realm.update
customer.session.create
customer.session.login
customer.unittest.run
customer.unittest.runAll
customer.user.create
customer.user.delete
customer.user.retrieve
customer.user.search
customer.user.update

customer.apikey.create

Create a new API key in a realm.

The api key alias must be unique across the whole of Zimki.

This method takes an implicit and required session_id parameter.

Returns XML describing the new api key

arguments

name	type	description	required
realm_id	text	The realm to create the key for	required
name	text	A name for the api key	optional
alias	text	The alias for the new api key.	optional

response

<response>
  <api_key revoked="0" issue_date="2005-10-31T14:49:47" name="name goes here" alias="alias" id="987331AC-4A1D-11DA-98F1-DDB51046DF9C" url="http://realm.url"/>
</response>

customer.apikey.update

Update an existing api key in a realm.

The api key alias must be unique across the whole of Zimki.

A revoked api key can't be used to access your realm, but does maintain it's alias, effectively reserving it.

This method takes an implicit and required session_id parameter.

Returns XML describing the new api key

arguments

name	type	description	required
api_key	text	The API key.	required
name	text	change the name to something else	optional
revoked	text	revoke the key\?	optional
alias	text	change the alias	optional

response

<response>
  <api_key revoked="0" issue_date="2005-10-31T14:49:47" name="name goes here" alias="alias" id="987331AC-4A1D-11DA-98F1-DDB51046DF9C" url="http://realm.url"/>
</response>

customer.billing.chargesByDay

Return billing data for the period between 'start' and 'finish', broken down by day. Both these parameters should be ISO8601 datetimes - the 'start' time will be truncated to the midnight before or at the passed time, and the 'finish' time will be extended to the end of the day containing the passed date.

If 'realm_id' is passed, billing data for only that realm will be returned, otherwise all realms' data will be returned.

The call list can become long, so if 'min_count' is passed, only paths that have been visited at least min_count times will be returned in the data.

arguments

name	type	description	required
realm_id	text	The realm to limit the report to	optional
start	text	timestamp at the beginning of the period	required
finish	text	timestamp at the end of the period	required
min_count	text	Limit returned call data to only paths visited at least this many times	optional
aggregate	text	Combine data from all realms into one 'day' node per day	optional

response

<response>
  <data>
    <day realm_id="id" time="2006-09-01T12:00:00+00:00" jsops="1" storage="2" bandwidth="3" special="4" total="10" burn="4">
      <call type="publishPath" info="/foo/bar/baz.html" count="34"/>
      <call type="publishPath" info="/foo/bar/baz.html" count="34"/>
    </day>
    <day realm_id="id" time="2006-09-01T12:00:00+00:00" jsops="1" storage="2" bandwidth="3" special="4" total="10" burn="4">
      <call type="publishPath" info="/foo/bar/baz.html" count="34"/>
      <call type="publishPath" info="/foo/bar/baz.html" count="34"/>
    </day>
  </data>
</response>

customer.billing.chargesByHour

Return billing data for the period between 'start' and 'finish', broken down by hour. Both these parameters should be ISO8601 datetimes - the 'start' time will be truncated to the hour boundary before or at the passed time, and the 'finish' time will be extended to the end of the hour passed.

If 'realm_id' is passed, billing data for only that realm will be returned, otherwise all realms' data will be returned.

The call list can become long, so if 'min_count' is passed, only paths that have been visited at least min_count times will be returned in the data.

arguments

name	type	description	required
start	text	timestamp at the beginning of the period	required
finish	text	timestamp at the end of the period	required
realm_id	text	The realm to limit the report to	optional
min_count	text	Limit returned call data to only paths visited at least this many times	optional
aggregate	text	Combine data from all realms into one 'hour' node per hour	optional

response

<response>
  <data>
    <hour realm_id="id" time="2006-09-01T12:00:00+00:00" jsops="1" storage="2" bandwidth="3" special="4" total="10">
      <call type="publishPath" info="/foo/bar/baz.html" count="34"/>
      <call type="publishPath" info="/foo/bar/baz.html" count="34"/>
    </hour>
    <hour realm_id="id" time="2006-09-01T12:00:00+00:00" jsops="1" storage="2" bandwidth="3" special="4" total="10">
      <call type="publishPath" info="/foo/bar/baz.html" count="34"/>
      <call type="publishPath" info="/foo/bar/baz.html" count="34"/>
    </hour>
  </data>
</response>

customer.billing.pendingPurchases

returns a list of all purchases that have been asked for by the user, but have yet to be approved.

arguments

name	type	description	required
start	text	timestamp at the beginning of the period	required
finish	text	timestamp at the end of the period	required

response

<response>
  <data>
    <pendingPurchase id="uuid" time="2006-09-01T12:00:00+00:00" tokens="" paid="" source="" note="" rejected=""/>
    <pendingPurchase id="uuid" time="2006-09-01T12:00:00+00:00" tokens="" paid="" source="" note="" rejected=""/>
  </data>
</response>

customer.billing.purchases

Returns a list of all token purchases made by the user that have been approved, between the passed times.

arguments

name	type	description	required
start	text	timestamp at the beginning of the period	required
finish	text	timestamp at the end of the period	required

response

<response>
  <data>
    <purchase id="uuid" time="2006-09-01T12:00:00+00:00" tokens="32545" paid="" source="" note=""/>
    <purchase id="uuid" time="2006-09-01T12:13:00+00:00" tokens="76546745" paid="" source="" note=""/>
  </data>
</response>

customer.class.create

Create a new class. All persisted object must be instances of a class.

The security model is very simple - the permissions on a class define which users / groups can create instances of these classes. The 'instance_permissions' attribute defines the default permissions of objects created by these users.

This method takes implicit and required api_key and session_id parameters.

arguments

name	type	description	required
realm_id	text	The realm we're working in	required
name	text	the name of the new class	required
permissions	text	the permissions for the new class	required
instance_permissions	text	permissions to give to new instances of this class	required
owner_id	text	The classes owner	optional
group_id	text	The group the class will belong to	optional

response

<response>
  <class name="classname" permissions="0xffffff" instance_permissions="0xffffff" owner_id="452273BC-712F-4EBD-B791-0AF2BD77401D" group_id="51108C86-6BCF-4187-A14D-53441DF5BA07"/>
</response>

customer.class.delete

Deletes a defined class. Will alse delete all instances of this class.

This method takes implicit and required api_key and session_id parameters.

arguments

name	type	description	required
realm_id	text	The realm we're working in	required
name	text	the name of the class to delete	required

response

<response></response>

customer.class.search

Searches for classes in a realm. If no search arguments are passed, all classes are returned. If a 'name' argument is passed, classes whose name is the same as the passed value are returned. You can also pass 'name__startswith' or 'name__notstartswith' arguments to return classes whose name starts or doesn't start with the passed value.

This call returned paged data. Use the 'per_page' and 'page' arguments to control the paging.

This method takes implicit and required api_key and session_id parameters.

arguments

name	type	description	required
page	text	The page number (defaults to 1)	optional
per_page	text	Number of entries per page	optional
realm_id	text	The realm we're working in	required
__other	text	Search args (e.g. name__startswith or name__notstartswith)	required

response

<response>
  <resultset pages="4" page="1" per_page="2">
    <class name="classname" permissions="0xffffff" instance_permissions="0xffffff" owner_id="452273BC-712F-4EBD-B791-0AF2BD77401D" group_id="51108C86-6BCF-4187-A14D-53441DF5BA07"/>
    <class name="classname" permissions="0xffffff" instance_permissions="0xffffff" owner_id="452273BC-712F-4EBD-B791-0AF2BD77401D" group_id="51108C86-6BCF-4187-A14D-53441DF5BA07"/>
  </resultset>
</response>

customer.class.update

This method lets you change the permissions and instance_permissions of an existing class. Class names cannot be changed.

This method takes implicit and required api_key and session_id parameters.

arguments

name	type	description	required
realm_id	text	The realm we're working in	required
name	text	the name of the class to update	required
permissions	text	the new class permissions	optional
instance_permissions	text	the new class instance permissions	optional
owner_id	text	The new owner of the class	optional
group_id	text	The group the class will belong to	optional

response

<response>
  <class name="classname" permissions="0xffffff" instance_permissions="0xffffff" owner_id="452273BC-712F-4EBD-B791-0AF2BD77401D" group_id="51108C86-6BCF-4187-A14D-53441DF5BA07"/>
</response>

customer.file.create

Upload a file into zimki. This won't make the file visible to the outside world, however - you'll need to explicitly publish it to achieve that.

The name field is the only human-readable way you will be able to identify this file after upload, other than remembering the ID returned from this method. It will default to the filename of the upload, but you can set it if you prefer something else.

This method takes implicit and required api_key and session_id parameters.

arguments

name	type	description	required
file	text	The file to upload, as an HTTP upload	required
realm_id	text	The realm that will own this file	required
owner_id	text	the owner_id to give to the file	optional
group_id	text	the group_id to give to the file	optional
permissions	text	the permissions to give to the file	optional
name	text	A human-readable text name for the file. Defaults to the upload filename.	optional
mimetype	text	Set if you want to force the mimetype of the uploaded file to something in particular. Autodetected otherwise.	optional
expires	text	When the file should expire, if at all. Use an ISO8601 datetime, or a string like '+1h' for 'in one hour'	optional

response

<response>
  <file id="0F4E8148-107F-408C-972B-D2451600A553" filesize="1234" mimetype="image/jpeg" created="2004-05-01T12:00" expires="2005-04-01T12:00" owner_id="owner" group_id="group" permissions="0x765" dent_url="for internal use only">
    <name>a description of the file.</name>
    <location url="/some/publish/url" created="2004-05-10T12:00"/>
    <location url="/some/publish/url" created="2004-05-10T12:00"/>
  </file>
</response>

customer.file.delete

Delete an uploaded file.

arguments

name	type	description	required
realm_id	text	The realm owning these files	required
file_id	text	the ID of the file to delete	required

response

<response></response>

customer.file.publish

Publish a file. This will make the file with the given ID available on the zimki endpoint by a combination of the current realm_id and the url you pass. Specifically, the url of a file published at will be something like

http://{alias}

arguments

name	type	description	required
realm_id	text	The realm owning these files	required
file_id	text	the id of the file to publish	required
url	text	the relative url to publish to	required

response

<response>
  <file id="0F4E8148-107F-408C-972B-D2451600A553" filesize="1234" mimetype="image/jpeg" created="2004-05-01T12:00" expires="2005-04-01T12:00" owner_id="owner" group_id="group" permissions="0x765" dent_url="for internal use only">
    <name>a description of the file.</name>
    <location url="/some/publish/url" created="2004-05-10T12:00"/>
    <location url="/some/publish/url" created="2004-05-10T12:00"/>
  </file>
</response>

customer.file.search

Lists the files uploaded.

If pased, the 'glob' argument will restrict the search to only files published to paths that match the argument, using unix glob semantics ('*' matches any number of characters, '\?' matches one).

arguments

name	type	description	required
page	text	The page number (defaults to 1)	optional
per_page	text	Number of entries per page	optional
realm_id	text	The realm owning these files	required
glob	text	return only files published to a path that matches the given glob	optional

response

<response>
  <resultset pages="4" page="1" per_page="2">
    <file id="0F4E8148-107F-408C-972B-D2451600A553" filesize="1234" mimetype="image/jpeg" created="2004-05-01T12:00" expires="2005-04-01T12:00" owner_id="owner" group_id="group" permissions="0x765" dent_url="for internal use only">
      <name>a description of the file.</name>
      <location url="/some/publish/url" created="2004-05-10T12:00"/>
      <location url="/some/publish/url" created="2004-05-10T12:00"/>
    </file>
    <file id="0F4E8148-107F-408C-972B-D2451600A553" filesize="1234" mimetype="image/jpeg" created="2004-05-01T12:00" expires="2005-04-01T12:00" owner_id="owner" group_id="group" permissions="0x765" dent_url="for internal use only">
      <name>a description of the file.</name>
      <location url="/some/publish/url" created="2004-05-10T12:00"/>
      <location url="/some/publish/url" created="2004-05-10T12:00"/>
    </file>
  </resultset>
</response>

customer.file.unpublish

Unpublish a file - it will no longer be available from the passed url, assuming it was to begin with.

Both file_id and url are optional - but you must pass one of them. If you pass only file_id, all publications of that file will be removed. If you pass only url, any file published to that url will be unpublished.

arguments

name	type	description	required
realm_id	text	The realm owning these files	required
file_id	text	the id of the file to unpublish. Can be left blank to just unpublish whetever is at the given url	optional
url	text	the url of the publication you want to remove. Can be left blank to unpublish all urls of the given file.	optional

response

<response>
  <file id="0F4E8148-107F-408C-972B-D2451600A553" filesize="1234" mimetype="image/jpeg" created="2004-05-01T12:00" expires="2005-04-01T12:00" owner_id="owner" group_id="group" permissions="0x765" dent_url="for internal use only">
    <name>a description of the file.</name>
    <location url="/some/publish/url" created="2004-05-10T12:00"/>
    <location url="/some/publish/url" created="2004-05-10T12:00"/>
  </file>
</response>

customer.file.update

Change the name, group, owner or permissions of an already-uploaded file.

arguments

name	type	description	required
realm_id	text	The realm owning these files	required
file_id	text	the id of the file to update	required
owner_id	text	the new owner_id of the file	optional
group_id	text	the new group_id of the file	optional
permissions	text	the new permissions for the file	optional
name	text	the new name for the file	optional
mimetype	text	the new mime type for the file	optional
expires	text	the new expires time of the file	optional

response

<response>
  <file id="0F4E8148-107F-408C-972B-D2451600A553" filesize="1234" mimetype="image/jpeg" created="2004-05-01T12:00" expires="2005-04-01T12:00" owner_id="owner" group_id="group" permissions="0x765" dent_url="for internal use only">
    <name>a description of the file.</name>
    <location url="/some/publish/url" created="2004-05-10T12:00"/>
    <location url="/some/publish/url" created="2004-05-10T12:00"/>
  </file>
</response>

customer.group.create

Create a group.

This method takes implicit and required api_key and session_id parameters.

arguments

name	type	description	required
realm_id	text	the target realm	required
name	text	the requested groupname	required

response

<response>
  <group id="8361EF97-3DBC-44DE-A33B-F6E99C3EFE7A" name="foo" users="12845">
    <user id="2471880F-8B7C-428B-8590-343D00484096" username="foo" created="2005-01-34T12:00" last_login="2005-01-34T12:00"/>
    <user id="2471880F-8B7C-428B-8590-343D00484096" username="foo" created="2005-01-34T12:00" last_login="2005-01-34T12:00"/>
  </group>
</response>

customer.group.delete

Delete a group.

This method takes implicit and required api_key and session_id parameters.

arguments

name	type	description	required
realm_id	text	the target realm	required
group_id	text	The ID of the group to delete	required

response

<response></response>

customer.group.retrieve

This returns the details of a group. The optional 'want_users' parameter, if true, will include in the returned XML a list of every user in this group.

This method takes implicit and required api_key and session_id parameters.

arguments

name	type	description	required
realm_id	text	the target realm	required
group_id	text	the group id	required
want_users	text	do we want the full userlist returned\?	optional

response

<response>
  <group id="8361EF97-3DBC-44DE-A33B-F6E99C3EFE7A" name="foo" users="12845">
    <user id="2471880F-8B7C-428B-8590-343D00484096" username="foo" created="2005-01-34T12:00" last_login="2005-01-34T12:00"/>
    <user id="2471880F-8B7C-428B-8590-343D00484096" username="foo" created="2005-01-34T12:00" last_login="2005-01-34T12:00"/>
  </group>
</response>

customer.group.search

Returns a list of groups. If the 'want_users' parameter is passed, the users that are in those groups will be returned as well, otherwise only the groups will be returned.

This call returned paged data. Use the 'per_page' and 'page' arguments to control the paging.

This method takes an implicit and required session_id parameter.

arguments

name	type	description	required
realm_id	text	the realm to search in	required
page	text	The page number (defaults to 1)	optional
per_page	text	Number of entries per page	optional
want_users	text	return user information as well	optional

response

<response>
  <resultset pages="4" page="1" per_page="2">
    <group id="8361EF97-3DBC-44DE-A33B-F6E99C3EFE7A" name="foo" users="12845">
      <user id="2471880F-8B7C-428B-8590-343D00484096" username="foo" created="2005-01-34T12:00" last_login="2005-01-34T12:00"/>
      <user id="2471880F-8B7C-428B-8590-343D00484096" username="foo" created="2005-01-34T12:00" last_login="2005-01-34T12:00"/>
    </group>
    <group id="8361EF97-3DBC-44DE-A33B-F6E99C3EFE7A" name="foo" users="12845">
      <user id="2471880F-8B7C-428B-8590-343D00484096" username="foo" created="2005-01-34T12:00" last_login="2005-01-34T12:00"/>
      <user id="2471880F-8B7C-428B-8590-343D00484096" username="foo" created="2005-01-34T12:00" last_login="2005-01-34T12:00"/>
    </group>
  </resultset>
</response>

customer.group.update

Update the details of a group.

This call will also let you set a list of user_ids that are in the group. _If_ a list of userids is passed, then any users that are already in the group but _aren't_ in the passed list will be removed from the group.

This method takes implicit and required api_key and session_id parameters.

arguments

name	type	description	required
realm_id	text	the target realm	required
group_id	text	the group id	required
name	text	new name	optional
want_users	text	do we want the full userlist returned\?	optional
user_ids	text	new list of users	optional

response

<response>
  <group id="8361EF97-3DBC-44DE-A33B-F6E99C3EFE7A" name="foo" users="12845">
    <user id="2471880F-8B7C-428B-8590-343D00484096" username="foo" created="2005-01-34T12:00" last_login="2005-01-34T12:00"/>
    <user id="2471880F-8B7C-428B-8590-343D00484096" username="foo" created="2005-01-34T12:00" last_login="2005-01-34T12:00"/>
  </group>
</response>

customer.instance.create

Any arguments provided to the method beyond those listed below are used as the initial state of the object's attributes.

An object has a special attribute 'expires', which may be set here. After this time, the object will no longer be accessible to API calls. The expires attribute can be set to either an ISO8601 datetime string, or a string such as '+1h', in which case the object will expire in one hour's time.

This method takes implicit and required api_key and session_id parameters.

arguments

name	type	description	required
realm_id	text	The realm we're working in	required
class	text	the name of the class you are creating an instance of	required
__other	text	The initial state of the created object	optional

response

<response>
  <instance class="classname" id="5BAA65C6-AE60-4194-B075-0899B64E39DD" owner_id="foo" group_id="bar" permissions="1248753">
    <attribute name="foo" type="string">fooo</attribute>
    <attribute name="bar" type="string">baaaar</attribute>
  </instance>
</response>

customer.instance.delete

Delete an instance of a class

This method takes implicit and required api_key and session_id parameters.

arguments

name	type	description	required
realm_id	text	The realm we're working in	required
class	text	the class of the instance you want to delete	required
instance_id	text	the ID of the instance you wish to delete	required

response

<response></response>

customer.instance.deleteAttributes

Deletes attributes from an instance. The 'delete' param should be a comma-seperated list of attributes to delete. You can't (as-yet) delete arguments with commas in their names.

arguments

name	type	description	required
realm_id	text	The realm we're working in	required
class	text	the class of the instance you want to change	required
instance_id	text	the ID of the instance you wish to change	required
delete	text	the attributes to delete	required

response

<response>
  <instance class="classname" id="5BAA65C6-AE60-4194-B075-0899B64E39DD" owner_id="foo" group_id="bar" permissions="1248753">
    <attribute name="foo" type="string">fooo</attribute>
    <attribute name="bar" type="string">baaaar</attribute>
  </instance>
</response>

customer.instance.deleteWhere

Delete instances of a class. Arguments to this method beyond those listed below are interpreted as searches on the attributes of the persisted object. Returns the number of instances deleted.

This method takes implicit and required api_key and session_id parameters.

arguments

name	type	description	required
realm_id	text	The realm we're working in	required
class	text		required
__other	text		required

response

<response>
  <deleted>3</deleted>
</response>

customer.instance.retrieve

Returns the instance of the given class and ID, as XML.

This method takes implicit and required api_key and session_id parameters.

arguments

name	type	description	required
realm_id	text	The realm we're working in	required
class	text	the class of the instance you want the details of	required
instance_id	text	the ID of the instance you want the details of	required

response

<response>
  <instance class="classname" id="5BAA65C6-AE60-4194-B075-0899B64E39DD" owner_id="foo" group_id="bar" permissions="1248753">
    <attribute name="foo" type="string">fooo</attribute>
    <attribute name="bar" type="string">baaaar</attribute>
  </instance>
</response>

customer.instance.search

Find instances of a class. Arguments to this method beyond those listed below are interpreted as searches on the attributes of the persisted objects.

See the docs for the JavaScript persist method 'search' for documentation on the search parameter format.

This method takes implicit and required api_key and session_id parameters.

This call returned paged data. Use the 'per_page' and 'page' arguments to control the paging.

arguments

name	type	description	required
realm_id	text	The realm we're working in	required
class	text		required
page	text	The page number (defaults to 1)	optional
per_page	text	Number of entries per page	optional
__other	text	search terms	required

response

<response>
  <resultset pages="4" page="1" per_page="2">
    <instance class="classname" id="5BAA65C6-AE60-4194-B075-0899B64E39DD" owner_id="foo" group_id="bar" permissions="1248753">
      <attribute name="foo" type="string">fooo</attribute>
      <attribute name="bar" type="string">baaaar</attribute>
    </instance>
    <instance class="classname" id="5BAA65C6-AE60-4194-B075-0899B64E39DD" owner_id="foo" group_id="bar" permissions="1248753">
      <attribute name="foo" type="string">fooo</attribute>
      <attribute name="bar" type="string">baaaar</attribute>
    </instance>
  </resultset>
</response>

customer.instance.update

Change the properties of an instance of a class. Currently, you can only add and set properties using this method. Use customer.instance.deleteAttributes to remove properties of an object.

All arguments to this method beyond those listed below are set as properties of the object. Any existing properties of the object not sent as arguments will not be changed.

This method takes implicit and required api_key and session_id parameters.

arguments

name	type	description	required
realm_id	text	The realm we're working in	required
class	text	the class of the instance you want to change	required
instance_id	text	the ID of the instance you wish to change	required
__other	text		required

response

<response>
  <instance class="classname" id="5BAA65C6-AE60-4194-B075-0899B64E39DD" owner_id="foo" group_id="bar" permissions="1248753">
    <attribute name="foo" type="string">fooo</attribute>
    <attribute name="bar" type="string">baaaar</attribute>
  </instance>
</response>

customer.javascript.run

run some arbitrary JS code in the context. Useful for creating classes, doing initial setup, etc

Returns the result returned from the JavaScript call, formatted as JSON.

arguments

name	type	description	required
realm_id	text	The realm we're working in	required
code	text	the code to evaluate	required

response

<response>
  <return>the return value of the code</return>
</response>

customer.realm.copy

Copy the realm specified by the source_realm_id argument. If target_realm_id is specified, the source realm will be copied into the target realm, otherwise a new realm (named with the 'target_name' argument) will be created, and the source will be copied into it.

The 'classes' argument should be a comma-seperated list of clasnames to copy, if you want to restrict your copy to a subset of the domain. Likewise, the 'files' argument should be '1' to copy the files in the domain, and '0' to not. If the 'all_classes' argument is set, all the classes in the source domain will be copied.

As a special case, if none of the optional arguments classes, files, or all_classes are specified all files, users, classes and instances will be copied.

This method takes an implicit and required session_id parameter.

Returns XML describing the target realm.

arguments

name	type	description	required
source_realm_id	text	the realm to be copyd	required
target_realm_id	text	the realm to copy to - if omitted, a new realm will be created	optional
target_name	text	The name to use for the target realm. If not specified, will keep the existing.	optional
all_classes	text	copy all classes, instead of just those listed	optional
classes	text	list of classes to copy	optional
files	text	1 if we should copy files\; 0 (the default) otherwise	optional

response

<response>
  <realm id="1148215D-2F88-42DE-86B2-6BFDF46BEEA7" name="Test" public="1" storage_quota="100" storage_used="1" deleted="0">
    <tokens allowance="3000" today="123" yesterday="1234" sevenDayAverage="2345" todayBurn="0" yesterdayBurn="0" sevenDayAverageBurn="0"/>
    <suspended date="iso8601 date" reason="suspended reason"/>
    <api_key active="1" revoked="0" issue_date="2005-10-31T14:49:47" name="name goes here" alias="alias" id="987331AC-4A1D-11DA-98F1-DDB51046DF9C" url="http://realm.url"/>
    <api_key active="0" revoked="0" issue_date="2005-10-31T14:49:47" name="name goes here" alias="alias" id="987331AC-4A1D-11DA-98F1-DDB51046DF9C" url="http://realm.url"/>
  </realm>
</response>

customer.realm.create

Create a new realm. You are limited to a maximum of 50 realms per account.

This method takes an implicit and required session_id parameter.

Returns XML describing the new realm.

arguments

name	type	description	required
name	text	the name of the realm	optional
public	text	whether the realm should be public (cloneable) or not (default 0)	optional
copy_id	text	copy an existing realm with this ID (must be either marked public, or owned by the currently logged-in customer.	optional

response

<response>
  <realm id="1148215D-2F88-42DE-86B2-6BFDF46BEEA7" name="Test" public="1" storage_quota="100" storage_used="1" deleted="0">
    <tokens allowance="3000" today="123" yesterday="1234" sevenDayAverage="2345" todayBurn="0" yesterdayBurn="0" sevenDayAverageBurn="0"/>
    <suspended date="iso8601 date" reason="suspended reason"/>
    <api_key active="1" revoked="0" issue_date="2005-10-31T14:49:47" name="name goes here" alias="alias" id="987331AC-4A1D-11DA-98F1-DDB51046DF9C" url="http://realm.url"/>
    <api_key active="0" revoked="0" issue_date="2005-10-31T14:49:47" name="name goes here" alias="alias" id="987331AC-4A1D-11DA-98F1-DDB51046DF9C" url="http://realm.url"/>
  </realm>
</response>

customer.realm.delete

Delete a realm. This can't be undone - the realm and all the data in it will be removed.

This method takes an implicit and required session_id parameter.

arguments

name	type	description	required
realm_id	text	the id of the realm to delete	required

response

<response></response>

customer.realm.restore

Restore a realm from a backup. If a realm_id is given the restore happens into that realm, merging the data, otherwise a new realm is created and the restoration happens into that. Returns XML describing the new realm.

The file parameter should be a HTTP POST form upload of a previously-downloaded backup zipfile.

This method takes an implicit and required session_id parameter.

arguments

name	type	description	required
name	text	the name of the realm, if one is created.	optional
realm_id	text	the ID of the target realm, if you want to restore into an existing realm.	optional
file	text	a backup containing the realm to restore	required

response

<response>
  <realm id="1148215D-2F88-42DE-86B2-6BFDF46BEEA7" name="Test" public="1" storage_quota="100" storage_used="1" deleted="0">
    <tokens allowance="3000" today="123" yesterday="1234" sevenDayAverage="2345" todayBurn="0" yesterdayBurn="0" sevenDayAverageBurn="0"/>
    <suspended date="iso8601 date" reason="suspended reason"/>
    <api_key active="1" revoked="0" issue_date="2005-10-31T14:49:47" name="name goes here" alias="alias" id="987331AC-4A1D-11DA-98F1-DDB51046DF9C" url="http://realm.url"/>
    <api_key active="0" revoked="0" issue_date="2005-10-31T14:49:47" name="name goes here" alias="alias" id="987331AC-4A1D-11DA-98F1-DDB51046DF9C" url="http://realm.url"/>
  </realm>
</response>

customer.realm.retrieve

Retrieves information associated with a realm. This call just returns data about a realm - it changes nothing.

This method takes an implicit and required session_id parameter.

arguments

name	type	description	required
realm_id	text	the id of the realm	required

response

<response>
  <realm id="1148215D-2F88-42DE-86B2-6BFDF46BEEA7" name="Test" public="1" storage_quota="100" storage_used="1" deleted="0">
    <tokens allowance="3000" today="123" yesterday="1234" sevenDayAverage="2345" todayBurn="0" yesterdayBurn="0" sevenDayAverageBurn="0"/>
    <suspended date="iso8601 date" reason="suspended reason"/>
    <api_key active="1" revoked="0" issue_date="2005-10-31T14:49:47" name="name goes here" alias="alias" id="987331AC-4A1D-11DA-98F1-DDB51046DF9C" url="http://realm.url"/>
    <api_key active="0" revoked="0" issue_date="2005-10-31T14:49:47" name="name goes here" alias="alias" id="987331AC-4A1D-11DA-98F1-DDB51046DF9C" url="http://realm.url"/>
  </realm>
</response>

customer.realm.search

Searches the realms owned by the current customer. Searches can only be performed on the 'name' attribute of a realm - if this argument is passed, only realms with that name are returned, otherwise all realms are returned.

Results are paginated - use the page and per_page arguments to control the maximum number of results returned from a single call, and the page of results to return.

This method takes an implicit and required session_id parameter.

arguments

name	type	description	required
page	text	The page number	optional
per_page	text	Number of entries per page	optional
deleted	text	If true, return deleted realms as well	optional
name	text		optional

response

<response>
  <resultset pages="4" page="1" per_page="2">
    <realm id="1148215D-2F88-42DE-86B2-6BFDF46BEEA7" name="Test" public="1" storage_quota="100" storage_used="1" deleted="0">
      <tokens allowance="3000" today="123" yesterday="1234" sevenDayAverage="2345" todayBurn="0" yesterdayBurn="0" sevenDayAverageBurn="0"/>
      <suspended date="iso8601 date" reason="suspended reason"/>
      <api_key active="1" revoked="0" issue_date="2005-10-31T14:49:47" name="name goes here" alias="alias" id="987331AC-4A1D-11DA-98F1-DDB51046DF9C" url="http://realm.url"/>
      <api_key active="0" revoked="0" issue_date="2005-10-31T14:49:47" name="name goes here" alias="alias" id="987331AC-4A1D-11DA-98F1-DDB51046DF9C" url="http://realm.url"/>
    </realm>
    <realm id="1148215D-2F88-42DE-86B2-6BFDF46BEEA7" name="Test" public="1" storage_quota="100" storage_used="1" deleted="0">
      <tokens allowance="3000" today="123" yesterday="1234" sevenDayAverage="2345" todayBurn="0" yesterdayBurn="0" sevenDayAverageBurn="0"/>
      <suspended date="iso8601 date" reason="suspended reason"/>
      <api_key active="1" revoked="0" issue_date="2005-10-31T14:49:47" name="name goes here" alias="alias" id="987331AC-4A1D-11DA-98F1-DDB51046DF9C" url="http://realm.url"/>
      <api_key active="0" revoked="0" issue_date="2005-10-31T14:49:47" name="name goes here" alias="alias" id="987331AC-4A1D-11DA-98F1-DDB51046DF9C" url="http://realm.url"/>
    </realm>
  </resultset>
</response>

customer.realm.update

Update information about a realm.

This method takes an implicit and required session_id parameter.

Returns XML describing the updated realm.

arguments

name	type	description	required
realm_id	text	the realm's id	required
name	text	the name of the realm	optional
public	text	whether the argument should be public or not	optional

response

<response>
  <realm id="1148215D-2F88-42DE-86B2-6BFDF46BEEA7" name="Test" public="1" storage_quota="100" storage_used="1" deleted="0">
    <tokens allowance="3000" today="123" yesterday="1234" sevenDayAverage="2345" todayBurn="0" yesterdayBurn="0" sevenDayAverageBurn="0"/>
    <suspended date="iso8601 date" reason="suspended reason"/>
    <api_key active="1" revoked="0" issue_date="2005-10-31T14:49:47" name="name goes here" alias="alias" id="987331AC-4A1D-11DA-98F1-DDB51046DF9C" url="http://realm.url"/>
    <api_key active="0" revoked="0" issue_date="2005-10-31T14:49:47" name="name goes here" alias="alias" id="987331AC-4A1D-11DA-98F1-DDB51046DF9C" url="http://realm.url"/>
  </realm>
</response>

customer.session.create

Creates a new session. To log into the customer API, you'll need salt, and salt lives in a session, so you'll need to create a session first.

arguments

name

type

description

required

response

<response>
  <session id="12345">
    <salt>12345678</salt>
    <expires>2005-10-05 16:02:38Z</expires>
  </session>
</response>

Authenticates a customer session. This method requires a hash of the customer password and the session salt generated as follows:

hash = md5_hex(salt + md5_hex(password))

Where md5_hex is a function that returns an MD5 digest in hexidecimal form.

arguments

name	type	description	required
username	text	customer username (email address)	required
hash	text	password hash as described above	required
session_id	text	an authenticated session id	required

response

<response>
  <session id="12345">
    <salt>12345678</salt>
    <login id="2471880F-8B7C-428B-8590-343D00484096" email="foo" customer_id="cid"/>
    <expires>2005-10-05 16:02:38Z</expires>
  </session>
</response>

customer.unittest.run

run the unit test with the given id

arguments

name	type	description	required
realm_id	text	The realm we're working in	required
test_id	text	the id of the test to run	required

response

<response>
  <unittest id="452273BC-712F-4EBD-B791-0AF2BD77401D" name="My test" planned="4" ran="4" failed="0">
    <test pass="1" comment="about this assertion" error="error message"/>
    <test pass="1" comment="about this assertion" error="error message"/>
  </unittest>
</response>

customer.unittest.runAll

run all unit tests in the current realm

arguments

name	type	description	required
realm_id	text	The domain we're working in	required

response

<response>
  <unittests>
    <unittest id="452273BC-712F-4EBD-B791-0AF2BD77401D" name="My test" planned="4" ran="4" failed="0">
      <test pass="1" comment="about this assertion" error="error message"/>
      <test pass="1" comment="about this assertion" error="error message"/>
    </unittest>
    <unittest id="452273BC-712F-4EBD-B791-0AF2BD77401D" name="My test" planned="4" ran="4" failed="0">
      <test pass="1" comment="about this assertion" error="error message"/>
      <test pass="1" comment="about this assertion" error="error message"/>
    </unittest>
  </unittests>
</response>

customer.user.create

Register a new user. The secret you pass should be the md5hex of the new user's password. This is no more secure than sending the plain text of the password, of course, so try to do this method over https if you care about security.

This method takes an implicit and required session_id parameter.

arguments

name	type	description	required
realm_id	text	the target realm	required
username	text	the requested login	required
secret	text	the secret for the new user	required
group_ids	text	group_ids of groups to register the user into	optional

response

<response>
  <user id="2471880F-8B7C-428B-8590-343D00484096" username="foo" created="2005-01-34T12:00" last_login="2005-01-34T12:00">
    <group id="8361EF97-3DBC-44DE-A33B-F6E99C3EFE7A" name="foo"/>
    <group id="8361EF97-3DBC-44DE-A33B-F6E99C3EFE7A" name="foo"/>
  </user>
</response>

customer.user.delete

Delete a user. Any objects they own will not be deleted.

This method takes an implicit and required session_id parameter.

arguments

name	type	description	required
realm_id	text	the target realm	required
user_id	text	the user you want to delete	required

response

<response></response>

customer.user.retrieve

Return the details for a particular user, including their group membership.

This method takes an implicit and required session_id parameter.

arguments

name	type	description	required
realm_id	text	the target realm	required
user_id	text	the id of the user you want details for	required

response

<response>
  <user id="2471880F-8B7C-428B-8590-343D00484096" username="foo" created="2005-01-34T12:00" last_login="2005-01-34T12:00">
    <group id="8361EF97-3DBC-44DE-A33B-F6E99C3EFE7A" name="foo"/>
    <group id="8361EF97-3DBC-44DE-A33B-F6E99C3EFE7A" name="foo"/>
  </user>
</response>

customer.user.search

Returns a list of users for a realm. If the 'want_groups' argument is '1', then the user information returned will include XML describing each of the groups those users are in, otherwise only the users will be returned.

This call returned paged data. Use the 'per_page' and 'page' arguments to control the paging.

This method takes an implicit and required session_id parameter.

arguments

name	type	description	required
page	text	The page number (defaults to 1)	optional
per_page	text	Number of entries per page	optional
realm_id	text	the target realm	required
want_groups	text	whether to include group memberships	optional

response

<response>
  <resultset pages="4" page="1" per_page="2">
    <user id="2471880F-8B7C-428B-8590-343D00484096" username="foo" created="2005-01-34T12:00" last_login="2005-01-34T12:00">
      <group id="8361EF97-3DBC-44DE-A33B-F6E99C3EFE7A" name="foo"/>
      <group id="8361EF97-3DBC-44DE-A33B-F6E99C3EFE7A" name="foo"/>
    </user>
    <user id="2471880F-8B7C-428B-8590-343D00484096" username="foo" created="2005-01-34T12:00" last_login="2005-01-34T12:00">
      <group id="8361EF97-3DBC-44DE-A33B-F6E99C3EFE7A" name="foo"/>
      <group id="8361EF97-3DBC-44DE-A33B-F6E99C3EFE7A" name="foo"/>
    </user>
  </resultset>
</response>

customer.user.update

Update a user's details. This includes changing the groups that a user is in.

This method takes an implicit and required session_id parameter.

arguments

name	type	description	required
realm_id	text	the target realm	required
user_id	text	the id of the user you want to update	required
username	text	the new requested login	optional
secret	text	the new secret (md5hex hash of the user's password)	optional
group_ids	text	the new groups for the user	optional

response

<response>
  <user id="2471880F-8B7C-428B-8590-343D00484096" username="foo" created="2005-01-34T12:00" last_login="2005-01-34T12:00">
    <group id="8361EF97-3DBC-44DE-A33B-F6E99C3EFE7A" name="foo"/>
    <group id="8361EF97-3DBC-44DE-A33B-F6E99C3EFE7A" name="foo"/>
  </user>
</response>

ZimkiClientLibraries

undefined — 2007-03-16T16:28:01.299+00:00

Supported Zimki Client Libraries

Zimki Client library for .NET and mono

Coming soon

Zimki Client libraries for:

JavaScript
Java

zimki.publishPath

undefined — 2006-06-26T12:32:43.831+00:00

The 'publishPath' method attaches a function to a URL. It can take either a regex or a string as the URL. In the case that a string is provided as the first parameter to 'publishPath' the handler function is called with one parameter, an Object containing the CGI parameters that the URL is been called with. When 'publishPath' is provided with regex the handler function is also passed the actual path called as its second parameter, and the return value of the regular expression match.

For example:


function helloWorld ( args ) {
  return "Hello World";
}

function helloPath ( args, path, match ) {
  return "Hello " + match[1];
}

zimki.publishPath( "/hello", helloWorld );
zimki.publishPath( /^hello_(.+)/, helloPath );

If a file object is published to the same path as a a JavaScript function (via the File.publish method) the File object takes priority.

The return value from the function will be returned as the contents of the requested page. Return a string or E4X object to just return content. You can return an instance of a zimki.file object to return the contents of that file as the contents of the page. Finally, if you want more control over the mime-type and character set of the returned data, return an Object:


zimki.publishPath('/complex', function() {
  return {
    content: "that page is not found",
    mimetype: "text/plain",
    charset: "iso-8859-1",
    status: 404
  };
});

zimki.publishPath can also publish a simple string to a path:

zimki.publishPath('/static', 'This string will be published');

CookBook.E4X

undefined — 2006-07-24T08:21:14.141+00:00

E4X: JavaScript for XML

The Zimki JavaScript engine fully supports using E4X, meaning that you can use XML as first class data types. This allows you to write things like this:

function hello() {
  return <html>
    <head>
      <title>hello</title>
    </head>
    <body>
      <h1>Hello World</h1>
    </body>
  </html>
}
zimki.publishPath('/', hello);

Notice that there's no quotes around that chunk of HTML (JavaScript doesn't have multi-line strings; we'll get to that in a bit), meaning that the 'hello' function is not returning a string of HTML but an XML object (which happens to be valid HTML). We then publish the return value to the path '/', but you might want to play around in the JavaScript Console and just evaluate the return value of the 'hello' function instead.

Autovivification for the lazy typist

E4X allows you to do more interesting things than typing out multi-line blocks of XML though. For example, here's a different way to write the 'hello' function above:

function hello() {
  var ret = <html/>;
  ret.head.title = 'hello';
  ret.body.h1 = 'Hello World';
  return ret;
}

Not only does this involve less typing, it also involves less manual syntax checking; any autovivified nodes are automatically terminated properly so you don't have to worry about it.

Multiline strings

One thing E4X allows you to do is to fake multi-line strings. You can do something like this, for example (copy and paste this into the JavaScript Console in the Zimki Portal):

'' + <text>
We come in peace;
lay down your weapons and take me to your leader.
And take that finger out of your nose when facing an officer.
</text>;

Accessing attributes of an XML object

We saw above how to access element values of an XML object: we simply access the attribute. However, XML can have attributes too, and using E4X you can access these values too. Let's say we have a table, like so:

var hiscore = <table>
  <tr width="100%">
    <th>Team</th>
    <th>Score</th>
  </tr>
  <tr>
    <td>Arsenal</td>
    <td>10</td>
  </tr>
</table>;

We find that the table is too wide, and want to resize it to take only 50% of the width. Additionally, we want the header row to be 50px high. We can do that by directly manipulating the hiscore object like so:

hiscore.tr.@width = '50%';
hiscore.tr.@height = '50px';

Billing Overview

undefined — 2006-08-21T16:10:12.630+00:00

What are the fees and when do I have to pay them?

The following sets out how billing will work in zimki. We are currently refining our models according to average usage in order to make the service as attractive as possible to potential customers. During this interim period we will not be charging. We will make an announcement to all users confirming when charges will be introduced.

Zimki is a service aimed at making your life less complicated, and that goes for our billing system too. Zimki's charging agreement is based on a 'token per unit' billing structure; there are no set-up or upfront charges; you simply pay for usage.

Further information on the pricing structure can be located here

Here is how it works

In a nutshell, this is what we're going to charge for:

JavaScript Operations
- Every request that you make to the Zimki service will consume JavaScript Operations. The number of operations consumed per request will be converted into tokens.
Storage
- This is calculated as the maximum amount of megabytes stored during a day. The storage space used will calculated each day and converted to tokens.
Bandwidth
- This is calculated as megabytes transferred. Each time data is transferred between one of your realms or a third party the total megabytes transferred will be converted to tokens.
Premium services
- There is an additional charge for certain services, such as sending email. This is levied on a per unit basis.

Pay only for what you use. There is no minimum fee, and no start-up cost. You simply purchase tokens in blocks of 100,000. You will be able to buy tokens in advance which can be used to consume your JavaScript Operations, Storage, Bandwidth and any Premium services used.

The tokens can be consumed by any realm that you have created. If you run out of tokens, you may have a 'grace period', which will take the form of a number of tokens that can be consumed over a certain number of days before you must purchase new tokens.

Question

How do I find out how much my realms have cost in a month? I want to monitor my usage to see how many units of each service have been consumed.

Answer

The Zimki server adds up the tokens consumed for each service and displays the cumulative total graphically. The total number of paid for tokens as well as the remaining balance is also displayed. You will also be able produce a report on each of your realms (domains).

Quotas and Limitations

There are a few quotas and limitations that you need to be aware of, these include:

The amount of operations you can request in JavaScript
There is a limit to the storage available.
A maximum of 50 domains/realms per customer

CookBook.StaticFiles

undefined — 2006-07-19T10:13:52.305+00:00

In addition to publishing JavaScript functions to paths, you can also publish static files to paths. To upload a file using the portal, go to the Files section under REALMS in the left-hand menu. Click Choose File and pick a file you want to upload, then click on the Upload new file button.

A new line will appear in the table under the upload form, with basic details about the file you just uploaded. Your realm now knows about your file, but it is not publicly visible anywhere yet. To do that, you have to publish it to a path.

To publish a file click on the word "No" in the Publications column of the file list table. Enter '/' in the textbox that appears and click Publish. If you now visit your realm, you should see the file that you uploaded; I chose to upload an image, but you're free to upload a text file, a small movie or anything else.

Go back to the Files view and see that our file now has "Yes" listed under publications. This means it has been published to at least one path. Click on the word "Yes" to view or change the file's publication paths.

You can publish a file to multiple paths without uploading the file again, to avoid burning more of your storage quota than you really need to.

File.contents

undefined — 2006-06-27T16:52:38.773+00:00

See the content method.

File.content

undefined — 2007-01-24T10:34:02.097+00:00

Gets and sets the contents of the file.

Example:

var files = zimki.file.search();
var theFile = files[0];
var data = theFile.content();

zimki.log.warn

undefined — 2006-06-26T12:27:40.526+00:00

Writes a line into the zimki log at the warn level.

For example:

zimki.log.warn("there is a good chance that something may be going wrong")

zimki.log.error

undefined — 2006-06-26T12:27:59.752+00:00

Writes a line into the zimki log at the error level.

For example:

zimki.log.error("its all going wrong!")

zimki.log.debug

undefined — 2006-06-26T12:27:07.664+00:00

Writes a line into the zimki log at the debug level.

For example:

zimki.log.debug("isn't it nice that this information is logged")

Zimki Class

undefined — 2006-06-27T16:54:24.615+00:00

Instances of Zimki classes are persistable in the Zimki object store. These classes have names, and top-level objects are created in your JavaScript context for each class. These object will have methods defined on them to allow you to create, delete and search for instances of these classes. For instance, suppose that I have used the portal to create a new persistable class called MyClass. I can create an instance in JavaScript space, then change it's properties, and save it:

  var instance = MyClass.create();
  instance.my_name = "Rapunzel";
  instance.save();

Likewise, there are calls to search for instances:

  // search for all instances called 'Rapunzel':
  var results = MyClass.search({ my_name:'Rapunzel' });

  // get the first one
  var first = results[0];

You can also retrieve an instance directly by it's ID:

  var rapunzel = MyClass.get( first.id );

And you can use the search terms in the get call:

  // get the first instance called Rapunzel
  var rapunzel = MyClass.get({ my_name:'Rapunzel' });

To delete a class:

  // delete poor old Rapunzel
  rapunzel.deleteInstance();

New persistable classes can be created by using zimki.persist.

  zimki.persist.create("AnotherClass");
  var anotherInstance = AnotherClass.create();

Calls to zimki.persist.create will fail if the class already exists.

Zimki Documentation

zimki.session

zimki.session.user

zimki.session.login

XML API

zimki

Classes

File

ExternalAPI

Overview

Zimki External API

Customer External API

Setting the Response Type

See Also

ZimkiExternalAPI

zimki.captcha.create

arguments

Example response

zimki.captcha.verify

arguments

Example response

zimki.file.create

arguments

Example response

zimki.file.delete

arguments

Example response

zimki.file.search

arguments

Example response

zimki.file.unpublish

arguments

Example response

zimki.file.update

arguments

Example response

zimki.instance.create

arguments

Example response

zimki.instance.delete

arguments

Example response

zimki.instance.deleteAttributes

arguments

Example response

zimki.instance.deleteWhere

arguments

Example response

zimki.instance.retrieve

arguments

Example response

zimki.instance.search

arguments

Example response

zimki.instance.update

arguments

Example response

zimki.session.create

arguments

Example response

zimki.session.delete

arguments

Example response

zimki.session.login

arguments

Example response

zimki.session.retrieve

arguments

Example response

zimki.user.retrieve

arguments

Example response

zimki.user.update

arguments

Example response

CustomerExternalAPI

customer.apikey.create

arguments

response

customer.apikey.update