API Intro

Our API is available for all apps hosted on orga.zone. During development on your own servers, you can use the "ID token" to avoid cross-domain problems.

The idea is pretty simple: we offer a form builder and a simple, but robust REST API for anybody, who needs some backend features on their mobile apps. We have a strong focus on business apps. So part of the packages we offer are SSL certificates and free subdomains, if you upload your web app to us.

This also includes an integrated user management for you. The entry point for the API is:
https://apps.orga.zone/en/apiv2/
and the first thing you have to do, to use it: login as a valid user!

Create Users

https://apps.orga.zone/en/apiv2/gui-register.php?appname=YOURTAG
If you have uploaded your app and gave it a URL-Tag like "ex2", we offer you a public sign-up link in the user management, where users might sign up for your app.
The form sends a confirmation email with a link that MUST be clicked to activate the user. See under "sessions" how to start a verified session with a login.

Create Forms

The form generation is shown in the intro video and can be found in the admin section for each app. Each form gets an UNIQUE ID in the system that can be addressed via the API.
For that you may use the REST parameter &formid=<ID>

Database Storage

At its core, the API is your simple toolbox to our database table for data management. While we have some extra caching and index in place ABOVE the table, it helps you to understand the approach to take a look at the table itself:


Sessions

Once a user is registered, you can login the user with his email and password from your app. You create a session and you also get a session token (cross domain capability!) back - the token is optional.
In PHP:
$data = Array("login" => "[email protected]", "pw"=> md5("thepassword") ); //not valid!

Test user: puzzler(at)runbox.com
Password is MD5 encoded,
both values in a json object for "appdata":
{"login":"[email protected]","pw":"3c41ff681c1e3dcb68b4d8573bf1c74c"}

?appaction=login
&appname=ex2
&appid=test
&appdata=<? = urlencode(json_encode($data)) ?>


If you call the login from any other domain than *.orga.zone, you must then use the:

&token=xxxxxxxxx

value that you got back, which is valid for 30 minutes to run your session. The token is optional and only needed for cross domain identification.


Get User Details

The "showuser" command gives you details about the currently logged in user:


While the result is a multi-layered JSON dataset that looks like:

{"success":1,"data":{"OZINDEX":"4","OZMAIL":"[email protected]","OZPIN":"*","OZSTATUS":"confirmed","OZDETAILS":"{\"ip\":\"127.0.0.1\",\"creationdate\":\"20150521173304\",\"blocked\":\"\"}","rights":"{\"OZINDEX\":\"4\",\"OZAPPID\":\"23\",\"OZMERCHANTID\":\"1\",\"OZUSERID\":\"4\",\"OZSTATUS\":\"{\\\"package\\\":\\\"free\\\",\\\"ip\\\":\\\"127.0.0.1\\\",\\\"creationdate\\\":\\\"20150521173304\\\",\\\"blocked\\\":\\\"\\\"}\"}","ex2":"active"}}

and the password is NULLed out.


Get User By eMail

For communication apps and other apps with many users in one dataspace, you can fetch information about the users by eMail. If the user exists for a specific app, display his/her info via email. eMail is URL-encoded.

Update User Profile Details

The active user has a JSON encoded PROFILE in his details, you can set freely...
Setting appdata as the new profile:
appdata["firstname"]="Jim"
appdata["lastname"]="Kirk"
appdata["nickname"]="Captain"
and pushing this as a JSON field:


Invite an user to your app

For teamwork apps and every app you want to invite others to use, we have a process ready, creating an invite form with automated confirmation of the account. If the user does not exist, it will be created with a random password and invited to your app.
The destination link should be on your subdomain and we append the value ?to=<email> to the URL
appdata["to"]="[email protected]"
appdata["destination"]="https://ex2.orga.zone/"


Get Status

The "status" gives you the latest primary key and the amount of entries in the database for your app. You can filter with different additional values, that many developers need to sort and categorize their requests for different tasks:
last entry primary key & amount
or: Get the primary key of last entry, total amount of entries and use filter string "PROJECTS":


Push Data

With this you put data into the database. You have several fields to sort and categorize the data that is pushed. You may also assign the data to a form that you have created before, so the data will be visible in the administration area.
If you do not address a specific, existing form ID, the data is not visible in the administration area!

You get the database entry ID back - this is the unique primary index in the table (OZINDEX).

Pull Data

The counterpart to retrieve data out of the API is called "pull":
Get data:
Getting the data without a filter string, setting the JSON object to:
$data = Array("datetime" => "201502280000", "pageno" => 0)
where "datetime" in the appdata JSON defines the start date and time of the entries
and the pageno=0 defines the start page (it is 10 entries per page by default).


Get data
Same, only for filter string PROJECTS

Get data
Same again, only for filter string PROJECTS and appsortint=1234


Request by ID

When you push data up, you will get an UNIQUE ID as an big integer value. You can use this value to retrieve one specific entry.

Search data freely by keyword
Uses the sphinx search daemon to find up to 1000 entries with a certain keyword. Keyword URL encoded in appdata.
?appaction=search
&appname=ex2
&appid=
&appcollection=
&appdata=<urlencode(string)>


In our example "?appaction=search&appname=ex2&appid=&appdata=tarifa" the result looks like:

{"success":1,"data":[{"OZINDEX":"1535","OZAPPNAME":"ex2","OZAPPID":"API","OZUSRID":"1","OZFORMID":"22", "OZLASTUPDATE":"20150822083219","OZCOLLECTIONID":"COLLECTION","OZSORTKEY":"FILE","OZSORTINT":"0", "OZPARENTCHAIN":"","OZOBJID":"","OZOWNERSTR":"","OZAPPDATA": {"status":"UPLOADED","type":"FILE","path":"..\\/up\\/ex2\\/files\\/tarifa.xlsx", "url":"https:\\/\\/apps.orga.zone\\/up\\/ex2\\/files\\/tarifa.xlsx"}}]}

and if more results are found, you get them in one big JSON block.


Update Entries

You can also update existing data entries:
Update 1 entry
Updates 1 entry in the APIv2 table, where appdata equals the primary key (OZINDEX).
The sorter values and appdata are pushed over existing values.
OZINDEX must be the first entry in your appdata JSON and it will be removed from it, before update.
Setting the array for the JSON request:
$data = Array("OZINDEX"=>123, "field1" => "...", "field2" => "...", "field3" => "...")
with OZINDEX is the primary key of the entry to update.


Delete Entries

And naturally delete an existing entry...
Delete 1 entry
Deletes 1 entry from the APIv2 table, where appdata equals the primary key (OZINDEX).
The "sorter" fields are optional, but could limit the delete, if necessary in later versions.


Upload Files

To save a picture or document, the API also supports file uploads:
Upload a file
The API supports a POST to upload files up to 150 MB
and the file is stored relatively to the app directory:
for example: apps.orga.zone/up/ex3/files/NEWFILE.jpg
Allowed file types are: gif, jpg, png, doc, docx, ppt, pptx, xls, xlsx, zip, tgz and ics.
appaction:
appid:
appname:
appsortstr: (optional)
formid: (if you need to list it in the admin section)
file:



Download Files

Uploaded files are only available to registered users in an app. So direct linking is not allowed and must be routed thru the API. The name of the file is only the basename and the directory is created by the function.
Download a file
Getting a file is simple. Just note that you have to submit the basename of the file. Beware: this API call does not give you a result, but DIRECTLY jumps to the file and tries to open it.
appaction:
appid:
appname:
appdata:



Delete Files

There is one entry point in the API to delete the physical file AND the database entry of it.
Delete a file
Again the name of the file must be passed as the basename.
appaction:
appid:
appname:
appdata:



Search Files

You can search only for files, if you want to filter these out. All filter strings work accordingly.
Delete a file
Again the name of the file must be passed as the basename.


Sendmail

As a registered user you can send emails out of your app. The command is named "sendmail" and
takes the receiver, subject, text and even attachments from the appdata block.

appdata contains
to: [email protected]
subject: just a test
text: this may contain simple HTML code as well
attachment: dsc02342.jpg (optional - that file must exist in the app specific upload directory)