Deko API

Z Dokumentace
Přejít na: navigace, hledání

Aplikace Deko používá pro uložení dat databází CouchDB. Tato databáze komunikuje se světem pomocí protokolu HTTP - s trochou nadsázky lze říci, že aplikace Deko je speciální webový prohlížeč pro zobrazování stránek uložených v databázi CouchDB. Díky způsobu komunikace je velmi snadné přistupovat do databáze i z jiných programů. Velká část používaných webových technologií dneška nepotřebuje pro přístup do databáze CouchDB použité v aplikaci Deko žádné speciální prostředky.

Abyste mohli přistupovat do databáze aplikace Deko přímo ze svých aplikací, potřebujete pochopit databázi CouchDB - její popis najdete na různých internetových stránkách a potřebujete znát detaily uložení dat v aplikaci Deko - ty najdete zde.

Obsah

Formát jednotlivých typů dokumentů

Všechny dokumenty mají společné některé vlastnosti. Databáze CouchDB vyžaduje existenci položek _id a _rev, aplikace Deko pak vyžaduje existenci nejméně položku doctype. V položce doctype je uložená informace o typu obsahu v konkrétním dokumentu.

Společné položky

  • doctype - typ dokumentu. Možné hodnoty jsou popsané dále v textu (project, person, task, file, company, event, note, timesheet)
  • color - barva dokumentu. Očekávaná hodnota ve obvyklém formátu "#rrggbb", například "#ff0000" (červená)
  • creator - ID uživatele, který dokument vytvořil nebo převzal jeho vlastnictví
  • ctime - datum vytvoření dokumentu. Během existence dokumentu se nemění. Datum ve formátu ISO-8601 (například "2013-09-04T20:29:37")
  • mtime - datum poslední změny dokumentu. Při každém uložení dokumentu se zde zapíše aktuální datum a čas. Datum ve formátu ISO-8601 (například "2013-09-04T20:29:37")
  • zone - seznam bezpečnostních zón dokumentu. Zóny jsou uvedené svými ID.
  • custom - seznam uživatelem definovaných položek.
    • description - popis (jméno) položky. Text.
    • global - hodnota typu bool. Globální položky se nabízejí ve všech dokumentech.
    • type - typ položky, text (Text, Date, Bool, Number). Záleží na velikosti písmen.
    • value - hodnota položky


Seznam typů dokumentů

  • project - údaje o projektu. Projekt se v aplikaci Deko používá typicky jako kontejner pro další typy dokumentů
  • person - údaje o osobě (jméno, telefon, mail, foto)
  • task - úkol (jméno, popis, termín, stav)
  • file - jeden soubor (jméno, popis) uložený spolu se staršími verzemi
  • company - informace o firmě (jméno, popis, ičo, telefon, mail)
  • event - událost (datum, připomínky, opakování)
  • note - poznámka, informace o telefonních hovorech, mailech nebo prostě jen poznámka
  • timesheet - pracovní výkaz (jméno, popis, cena, seznam ze sledování času)
  • report - tisková sestava (html + javascript)
  • link - vazební dokument definující vztah mezi dvěma různými dokumenty

project

{
"idnumber", "",
"name" : "",
"description" : "",
"begindate" : "",
"enddate" : "",
"price" : "",
"status" : "",
"status_history" : [
        { 
            "date" : "",
            "status" : ""
        }
    ],
"doctype" : "project",
"color" : "#ff0000",
"creator" : "id",
"ctime" : "",
"mtime" : "",
"zone" : [ "id", "id", ...],
"custom" : [
        {
            "description": "",
            "global": "",
            "type": "",
            "value": "",
        }
    ],

}

Význam položek

  • idnumber - číslo projektu. Jednoduchý text. Nemá nikam žádnou vazbu, slouží pouze pro zobrazení. Položku můžete využít pro vytváření vazeb na externí informační systémy.
  • name - jméno projektu, jednoduchý text
  • description - popis projektu, jednoduchý text nebo html
  • begindate - začátek projektu, datum ve formátu ISO-8601 (například "2013-09-04T20:29:37")
  • enddate - konec projektu, datum ve formátu ISO-8601 (například "2013-09-04T20:29:37")
  • price - cena, desetinné číslo
  • status - momentální stav projektu, jednoduchý text
  • status_history - pole s objekty popisujícími vývoj stavu projektu v čase:
    • date - datum změny, datum ve formátu ISO-8601 (například "2013-09-04T20:29:37")
    • status - stav projektu, text

person

{
"firstname" : "",
"surname" : "",
"displayname", "",
"description" : "",
"birthday" : "",
"www" : "",
"facebook" : "",
"photo" : "",
"email" : [
        {
            "email" : "",
            "note" : "",
        }
    ],
"phone" : [
        {
            "phone" : "",
            "note" : "",
        }
    ],
"address" : "", 
"street" : "", 
"city" : "", 
"zip" : "", 
"county" : "", 
"state" : "", 
"latitude" : "", 
"longitude" : "", 
"doctype" : "person",
"color" : "#ff0000",
"creator" : "id",
"ctime" : "",
"mtime" : "",
"zone" : [ "id", "id", ...],
"custom" : [
        {
            "description": "",
            "global": "",
            "type": "",
            "value": "",
        }
    ],

}

Význam položek

  • firstname - křesní jméno, jednoduchý text
  • surname - příjmení, jednoduchý text
  • displayname - zobrazované jméno, jednoduchý text
  • description - popis projektu, jednoduchý text nebo html
  • birthday - datum narození, datum ve formátu ISO-8601 (například "2013-09-04")
  • www - odkaz na webové stránky. Uvádějte plnou URL, například http://www.hobrasoft.cz/
  • facebook - odkaz na facebook osoby.
  • photo - jméno přílohy s fotografií. Každý dokument může mít libovolný počet příloh. U osoby lze jednu z těchto příloh prohlásit za fotografii osoby - do položky photo se uloží jméno přílohy.
  • email - pole s objekty popisujícími emailové adresy
    • email - adresa elektronické pošty, například petr.bravenec@hobrasoft.cz
    • note - poznámka k adrese, jednoduchý text, například "Firemní adresa"
  • phone - pole s objekty popisujícími telefonní kontakty
    • phone - telefonní číslo, například "+420 777 566 384". Formát telefonního čísla není pevně daný, můžete zde uložit například i kontakt na Skype.
    • note - poznámka k číslu, jednoduchý text, například "Firemní adresa"
  • address - první řádek adresy, nemusí se vyplňovat, může nést doplňující informace například o firmě.
  • street - ulice
  • city - město
  • zip - poštovní směrovací číslo
  • county - okres, kraj, oblast nebo jiné označené většího územního celku
  • state - stát
  • latitude - zeměpisná šířka v desetinném formátu, server kladně
  • longitude - zeměpisná délka v desetinném formátu, východ kladně

task

{
"name" : "",
"description" : "",
"begindate" : "",
"enddate" : "",
"status" : "",
"doctype" : "task",
"color" : "#ff0000",
"creator" : "id",
"ctime" : "",
"mtime" : "",
"zone" : [ "id", "id", ...],
"custom" : [
        {
            "description": "",
            "global": "",
            "type": "",
            "value": "",
        }
    ],

}

Význam položek

  • name - název, jednoduchý text
  • description - popis projektu, jednoduchý text nebo html
  • begindate - začátek projektu, datum ve formátu ISO-8601 (například "2013-09-04T20:29:37")
  • enddate - konec projektu, datum ve formátu ISO-8601 (například "2013-09-04T20:29:37")
  • price - cena, desetinné číslo
  • status - momentální stav úkolu, text. Musí být prázdné, notstarted, started, stopped, canceled nebo finished (malými písmeny).

file

{
"name" : "",
"description" : "",
"doctype" : "file",
"color" : "#ff0000",
"creator" : "id",
"ctime" : "",
"mtime" : "",
"zone" : [ "id", "id", ...]
}

Význam položek

  • name - název, jednoduchý text
  • description - popis projektu, jednoduchý text nebo html

Dokument typu file neobsahuje uživatelsky definované položky (custom). Jednotlivé verze souboru se vkládají do dokumentu jako samostatné přílohy, jméno přílohy se volí tak, aby starší verze při třídění zůstávaly na konci seznamu. Aplikace Deko používá pro pojmenování verzí datum a čas ve formátu (Qt formát) yyyy-MM-dd hhmmss. Schéma pro pojmenování verzí může být libovolné, ale není zaručeno, že se v dalších verzích nemůže změnit nebo že nemůže být vyžadováno striktně nyní použíté schéma. Jako poslední verze se bere nejvyšší hodnota - při pojmenování verzí aaa, bbb a ccc by to byla verze ccc.

Při ukládání souboru (tlačítko Uložit) se nabízí jako jméno souboru obsah položky name.

company

{
"name" : "",
"description" : "",
"www" : "",
"facebook" : "",
"idnumber" : "",
"vatnumber" : "",
"email" : [
        {
            "email" : "",
            "note" : "",
        }
    ],
"phone" : [
        {
            "phone" : "",
            "note" : "",
        }
    ],
"address" : "", 
"street" : "", 
"city" : "", 
"zip" : "", 
"county" : "", 
"state" : "", 
"latitude" : "", 
"longitude" : "", 
"doctype" : "company",
"color" : "#ff0000",
"creator" : "id",
"ctime" : "",
"mtime" : "",
"zone" : [ "id", "id", ...],
"custom" : [
        {
            "description": "",
            "global": "",
            "type": "",
            "value": "",
        }
    ],

}

Význam položek

  • name - jméno, jednoduchý text
  • description - popis projektu, jednoduchý text nebo html
  • www - odkaz na webové stránky. Uvádějte plnou URL, například http://www.hobrasoft.cz/
  • facebook - odkaz na facebook osoby.
  • idnumber - IČO, jednoduchý text. V případě zahraničních firem nebo v případě použití aplikace Deko v zahraničí lze využít pro jiné účely.
  • vatnumber - DIČ, jednoduchý text. Má smysl v EU, jinde lze využít pro jiné účely.
  • email - pole s objekty popisujícími emailové adresy
    • email - adresa elektronické pošty, například petr.bravenec@hobrasoft.cz
    • note - poznámka k adrese, jednoduchý text, například "Firemní adresa"
  • phone - pole s objekty popisujícími telefonní kontakty
    • phone - telefonní číslo, například "+420 777 566 384". Formát telefonního čísla není pevně daný, můžete zde uložit například i kontakt na Skype.
    • note - poznámka k číslu, jednoduchý text, například "Firemní adresa"
  • address - první řádek adresy, nemusí se vyplňovat, může nést doplňující informace například o firmě.
  • street - ulice
  • city - město
  • zip - poštovní směrovací číslo
  • county - okres, kraj, oblast nebo jiné označené většího územního celku
  • state - stát
  • latitude - zeměpisná šířka v desetinném formátu, server kladně
  • longitude - zeměpisná délka v desetinném formátu, východ kladně

event

{
"name" : "",
"description" : "",
"datetime" : "",
"alarm" : true,
"repeating" : {
    "enddate" : "",
    "interval" : 1,
    "type" : daily,
    "special" : "mon"
    }
"doctype" : "event",
"color" : "#ff0000",
"creator" : "id",
"ctime" : "",
"mtime" : "",
"zone" : [ "id", "id", ...],
"custom" : [
        {
            "description": "",
            "global": "",
            "type": "",
            "value": "",
        }
    ],

}

Význam položek

  • name - název, jednoduchý text
  • description - popis projektu, jednoduchý text nebo html
  • begindate - datum události, datum a čas ve formátu ISO-8601 (například "2013-09-04T20:29:37")
  • alarm - bool položka. Pokud je true, aplikace Deko vám událost připomene.
  • repeating - objekt s informacemi o opakování. V případě, že událost nemá opakování, položka neexistuje, nebo je prázdná.
    • enddate - konec opakování, datum ve formátu ISO-8601 (například "2013-09-04T20:29:37")
    • special - textové vyjádření speciálního případu: mon, tue, wed, thu, fri, sat, sun nebo last-month-day. V případě, že je použitá tato položka, nesmí být použité následující dvě položky, interval a type.
    • interval - interval opakování, číslo. Musí být spojeno s položkou type a nesmí se vyskytovat s položkou special.
    • type - typ intervalu pro opakování: daily, weekly, monthly, yearly. Musí být uvedeno malými písmeny.

note

{
"name" : "",
"description" : "",
"datetime" : "",
"icon" : "",
"doctype" : "note",
"color" : "#ff0000",
"creator" : "id",
"ctime" : "",
"mtime" : "",
"zone" : [ "id", "id", ...],
"custom" : [
        {
            "description": "",
            "global": "",
            "type": "",
            "value": "",
        }
    ],

}

Význam položek

  • name - název, jednoduchý text
  • description - popis projektu, jednoduchý text nebo html
  • icon - označuje typ poznámky (liší se pouze ikonou v seznamu). Může být: prázdné (interpretuje se jako note), note, phone, meeting, email, message.

timesheet

{
"name" : "",
"description" : "",
"begindate" : "",
"enddate" : "",
"duration" : "",
"hourprice" : "",
"price" : "",
"trackable" : "",
"timetrack" : [
        {
            "from" : "",
            "to" : "",
        }
    ]
"doctype" : "timesheet",
"color" : "#ff0000",
"creator" : "id",
"ctime" : "",
"mtime" : "",
"zone" : [ "id", "id", ...],
"custom" : [
        {
            "description": "",
            "global": "",
            "type": "",
            "value": "",
        }
    ],

}

Význam položek

  • name - název, jednoduchý text
  • description - popis, jednoduchý text nebo html
  • begindate - datum začátku, datum ve formátu ISO-8601 (například "2013-09-04T20:29:37")
  • enddate - datum konce, datum ve formátu ISO-8601 (například "2013-09-04T20:29:37")
  • duration - délka trvání v hodinách, desetinné číslo
  • hourprice - cena za jednu hodinu, číslo
  • price - celková cena pracovního výkazu, číslo
  • trackable - boolean. Je-li true, zobrazuje se takový pracovní výkaz ve sledování času.
  • timetrack - záznamy z automatického sledování času, pole hodnot:
    • from - datum a čas začátku, datum ve formátu ISO-8601 (například "2013-09-04T20:29:37")
    • to - datum a čas konce, datum ve formátu ISO-8601 (například "2013-09-04T20:29:37")

report

{
"name" : "",
"description" : "",
"source" : "",
"doctype" : "report",
"color" : "#ff0000",
"creator" : "id",
"ctime" : "",
"mtime" : "",
"zone" : [ "id", "id", ...],
"custom" : [
        {
            "description": "",
            "global": "",
            "type": "",
            "value": "",
        }
    ],

}

Význam položek

  • name - název, jednoduchý text
  • description - popis projektu, jednoduchý text nebo html
  • source - zdrojový kód sestavy (html + javascript)

link

{
"_id" : "id-linku",
"doctype" : "link",
"id1" : "",
"id2" : "",
"doctype1" : "",
"doctype2" : ""
}

Význam položek

  • id1 - id nadřízeného dokumentu
  • id2 - id podřízený dokumentu
  • doctype1 - doctype nadřízeného dokumentu, typicky project
  • doctype2 - doctype podřízeného dokumentu

Vazební dokument existuje pro každý vztah nadřízený - podřízený. Položky označené jedničkou jsou vyhražené pro nadřízený, rodičovský, odkazující se dokument (kontejner, univerzálně a nejčastěji project, případně pro speciální případy company nebo person). Obě strany vztahu by měly existovat, ale vzhledem k replikacím je principiálně nemožné se na platnost vztahu spolehnout - nemusí existovat jedna nebo obě strany vazebního dokumenty, případně může být jeden vazební dokument se stejným významem uložen několikrát pod různými id. Takové stavy se vyhledávají a řeší v části Údržba databáze v aplikaci Deko.

Získávání dokumentů

Databáze CouchDB komunikuje se světem protokolem http a veškerá data se posílají ve formátu JSON. S databází je velmi snadné komunikovat pomocí nástrojů jako je curl (ať už na povelové řádce nebo v php). V dalším textu proto budeme používat právě tento nástroj.

V databázi má každý objekt svůj jednoznačný identifikátor - položku _id. Každá databáze aplikace Deko obsahuje několik pevně daných dokumentů, na kterých můžete vyzkoušet čtení dat z databáze. Ve svém webovém prohlížeči nebo pomocí nástroje curl z povelové řádky můžete přečíst některé známé údaje.

Přečtení informací o databázi:

curl -X GET http://127.0.0.1:5984/hobrasoft/
{
  "db_name":"hobrasoft",
  "doc_count":575,
  "doc_del_count":1945,
  "update_seq":4575,
  "purge_seq":0,
  "compact_running":false,
  "disk_size":3108987,
  "data_size":2976900,
  "instance_start_time":"1386860035852515",
  "disk_format_version":6,
  "committed_update_seq":4575
}

Přečtení kořenového projektu. Všimněte si, že dokument je zcela ořezaný a obsahuje pouze nezbytně nutné položky. Aplikace Deko zapisuje vše, ale existenci položek nevyžaduje. Při zápisu vlastních dokumentů toho můžete využít a usnadnit si práci:

curl -X GET http://127.0.0.1:5984/hobrasoft/root
{
  "_id":"root",
  "_rev":"1-22229696bb9c9441b4fa785a76cecd17",
  "doctype":"project",
  "name":"Root"
}

Přečtení verze databázového schématu. Číslo verze neměňte - ovlivnilo by to případné aktualizace:

curl -X GET http://127.0.0.1:5984/hobrasoft/dbversion
{
  "_id":"dbversion",
  "_rev":"56-4b39aacfd8a17f16c603906381ba3e01",
  "dbversion":202
}

Ukládání nových dokumentů

Dokumenty se ukládají stejným způsobem, jako se z databáze čtou. Místo příkazu GET použijte příkaz PUT. V databázi aplikace Deko si tak můžete vytvořit třeba vlastní projekt:

curl -X PUT http://127.0.0.1:5984/hobrasoft/0000aaaa -d '{ "doctype": "project", "name": "Vlastní projekt" }'

Co to uložilo?

curl -X GET http://127.0.0.1:5984/hobrasoft/0000aaaa
{
  "_id":"0000aaaa",
  "_rev":"1-44d078da2346f488a545ff981ba7d979",
  "doctype":"project",
  "name":"Vlastní projekt"
}

Když se nyní podíváte do své databáze aplikací Deko, nový projekt nebude vidět. Abyste projekt zviditelnili, můžete spustit údržbu databáze. Jedním z kroků při údržbě je i vyhledání osiřelých dokumentů - takové dokumenty se přiřadí do projektu Root. Takovou vazbu byste měli ale udělat sami, stačí vytvořit vazební dokument:

curl -X PUT http://127.0.0.1:5984/hobrasoft/0000aaaa-link -d '{ 
  "doctype": "link", 
  "id1" : "root", 
  "id2": "0000aaaa", 
  "doctype1": "project", 
  "doctype2" : "project"
}'

Pomocí aplikace Deko byste nyní měli vidět vlastní projekt v databázi.

Přepisování existujících dokumentů

Chcete-li přepsat v databázi existující dokument, použijte stejně jako při vkládání nových dokumentů příkaz PUT nástroje curl. Pokusíte-li se ovšem přepsat dokument způsobem popsaným výše, postaví se vám do cesty verzovací systém databáze CouchDB:

curl -X PUT http://127.0.0.1:5984/hobrasoft/0000aaaa -d '{ "doctype": "project", "name": "Nové jméno" }'
{"error":"conflict","reason":"Document update conflict."}

Abyste mohli přepsat existující dokument, musíte znát i číslo verze dokumentu, najdete je v položce _rev:

curl -X GET http://127.0.0.1:5984/hobrasoft/0000aaaa
{
  "_id":"0000aaaa",
  "_rev":"3-a748bb501fea972d48885fbf6f4243bf",
  "doctype":"project",
  "name":"Vlastní projekt"
}

Se znalostí položky _rev a _id už můžeme dokument přepsat:

curl -X PUT http://127.0.0.1:5984/hobrasoft/0000aaaa -d '{ 
  "_id" : "0000aaa",
  "_rev" : "3-a748bb501fea972d48885fbf6f4243bf",
  "doctype": "project", 
  "name": "Nové jméno" 
}'
{"ok":true,"id":"0000aaaa","rev":"4-554e9b41f0f00c1f29ba8ba5a358b794"}

Mazání dokumentů

Paradoxně může být mazání dokumentů ta nejobtížnější část při manipulaci s daty. Každý dokument je totiž v databázi postaven do nějakého kontextu, který však spolu s dokumentem nezmizí a proto je potřeba smazat i vazební dokumenty tvořící tento kontext. Aplikaci Deko naštěstí narušené vazby nevadí a lze je opravit v údržbě databáze.

Při mazání může nastat několik situací:

  1. Chcete smazat pouze vazbu mezi dokumenty. Chcete například, aby se dokument s kontaktem František Opička nenacházel v projektu ZOO. Zde stačí smazat pouze vazební dokument (doctype link), ale je třeba dbát na to, aby byl kontakt František Opička nadále odkazován jiným vazebním dokumentem z jiného projektu. Dokument bez vazeb by totiž nebyl v aplikaci Deko viditelný. Je potřeba vytvořit alespoň vazební dokument z projektu root.
  2. Chcete smazat dokument doopravdy - zde musíte smazat jak dokument samotný, tak i všechny vazební dokumenty odkazující se na smazaný dokument.
  3. Chcete smazat dokument doopravdy a dokument obsahuje další potomky - například projekt, který obsahuje několik kontaktů. V takovém případě musíte smazat dokument samotný a s podřízenými dokumenty naložit podle potřeby:
    1. Chcete smazat i podřízené dokumenty - rekurzivně opakujete tento postup i na podřízené dokumenty
    2. Podřízené dokumenty chcete zachovat - všechny vazby z tohoto dokumentu musíte převést na jiný dokument. V našem případě projektu s několika kontakty můžete kontakty přesunout například do projektu root.


Při mazání opět potřebujete znát číslo verze dokumentu, potom už je mazání jednoduché:

curl -X DELETE 'http://127.0.0.1:5984/hobrasoft/0000aaaa?rev=4-554e9b41f0f00c1f29ba8ba5a358b794'
{"ok":true,"id":"0000aaaa","rev":"5-6b3a0934c9da985bd8a51ecdfca02a14"}

Protože při mazání potřebujeme znát vazební dokumenty spojené s mazaným objektem, je v databázi několik pohledů, které poskytují potřebné informace. Každý dokument v databázi aplikace Deko má nejméně jeden vazební dokument, který říká, ve kterém projektu se dokument nachází - nadřízený objekt. Ten se dá zjistit z databázového view _design/lists/_view/links-to-me:

curl -X GET 'http://127.0.0.1:5984/hobrasoft/_design/lists/_view/links-to-me?key="0000aaa"'
{"total_rows":304,"offset":0,"rows":[
    {
    "id":"0000aaaa-link",
    "key":"0000aaaa",
    "value":{
        "linkid":"0000aaaa-link",
        "linkrev":"1-69305803a5fb45b2cc0bd9b3b92d3769",
        "docid":"root",
        "doctype":"project"
        }
    }
]}

Podobně pro zjištění podřízených dokumentů můžete použít databázové view _design/lists/_view/links-from-me:

curl -X GET 'http://127.0.0.1:5984/hobrasoft/_design/lists/_view/links-from-me?key="0000aaa"'
{"total_rows":304,"offset":0,"rows":[]}

Zde je počet odkazovaných dokumentů nulový. Ale můžeme to vyzkoušet na dokumentu root, který by měl vrátit množství hodnot (zkráceno):

curl -X GET 'http://127.0.0.1:5984/hobrasoft/_design/lists/_view/links-from-me?key="root"'
{"total_rows":304,"offset":299,"rows":[{
    "id":"0000aaaa-link",
    "key":"root",
    "value":{
        "linkid":"0000aaaa-link",
        "linkrev":"1-69305803a5fb45b2cc0bd9b3b92d3769",
        "docid":"0000aaaa",
        "doctype":"project"
        }
    }
]}

V obou případech, jak u databázového view _design/lists/_view/links-to-me, tak u databázového view _design/lists/_view/links-from-me je struktura vrácených hodnot stejná:

  • linkid - id vazebního dokumentu. Spolu s položkou linkrev je možné vrácené hodnoty rovnou využít pro smazání nebo modifikaci vazebního dokumentu
  • linkrev - číslo verze vazebního dokumentu.
  • docid - id odkazovaného či odkazujícího dokumentu. Význam se liší podle view - ve view links-to-me je zde id nadřízeného dokumentu, ve view links-to-me je zde id podřízeného dokumentu.
  • doctype - doctype odkazovaného či odkazujícího dokumentu.

Indexy, pohledy