ClipNote REST Api

verze 1.0.1

url serveru: https://ssl.meditorial.cz/clipnote
url testovacího serveru: https://ssl.meditorial.cz/clipnote-dev

URL http požadavků

URL se skládá z několika částí: api, verze, název metody a volitelně další parametry.

Zápis:

GET /{api}/{verze}/{metoda}[/{parametr}] HTTP/1.1

Příklad: Pošle požadavek k získání souboru s ID 12 na testovacím serveru, použitá verze API je 1.0.1.

GET /clipnote-dev/1.0.1/file/12 HTTP/1.1

Přihlášení

Přihlášení uživatele probíhá přes metodu login, která vrací session ID (SID). To je poté posíláno s každým dalším požadavkem v cookies. Pokud je poslán dotaz bez/s vypršelým SID, tak server vrátí status 401.

Metody

Případě úspěchu vrací server HTTP status 200. Tělo odpovědi je vždy ve formátu JSON. Pokud nastane nějaký problém, server vrátí některý ze statusů a případně popis problému v pramateru error.

Hotové metody:

login

/clipnote/1.0.1/login

get

Ověří stav přihlášení. Pokud je SID platné, tak se vrací objekt user, jinak vrací statusový kód 401.

post

Přihlásí uživatele. Pokud jsou údaje platné, vrací se objekt user a SID.

POST parametry:
loginstringuživatelské jméno
passwdstringuživatelské heslo zahashováno v MD5
Vrací:
useruserobjekt uživatele
SIDstring (32)session id posílané v dalších metodách

příklad

GET /clipnote/1.0.1/login HTTP/1.1
Cookie: SID=2de02b832676d1d45471016c736b3a6b
HTTP/1.1 200 OK
Content-Type: text/json
{"user":{"id":1,"login":"novak"....}}		
POST /clipnote/1.0.1/login HTTP/1.1
login=novak&passwd=a702955babd0e0c9bdcf176c13b60a1f
HTTP/1.1 401 Unauthorized
{"error":"bad login or password"}

logout

/clipnote/1.0.1/logout

get

Odhlásí uživatele.

příklad

GET /clipnote/1.0.1/logout HTTP/1.1
Cookie: SID=2de02b832676d1d45471016c736b3a6b
HTTP/1.1 200 OK

sync

/clipnote/1.0.1/sync

get

Metoda vrací kompletní seznam ID objektů dostupné pro přihlášeného uživatele.
GET parametrem může být určeno, že se místo ID budou posílat přímo objekty.
Dále se může GET parametrem určit datum poslední aktualizace - v tom případě se zašlou pouze ID (objekty) upravené, nebo smazané od tohoto data.
Přidáním URL parametru se může synchronizace zacílit pouze na jeden objekt (v tomto případě jsou ve struktuře vynechány ostatní objekty).

Metoda dále vrací seznam volitelných položek zobrazovaných v detailu lékaře. Tyto položky jsou vázány na společnost uživatele, takže při zadání parametru last_update se zašle seznam pouze v případě, je-li změněn objekt společnosti (jinak se vrací null).

GET parametry:
last_updateint[nepovinný] timestamp poslední aktualizace
/clipnote/1.0.1/sync?last_update={timestamp}
send_objectbool[nepovinný] pokud je nastaveno true, metoda vrací objekty místo ID
/clipnote/1.0.1/sync?send_object=true
URL parametry:
objectstring[nepovinný] uvedením parametru se synchronizují pouze udané objekty
/clipnote/1.0.1/sync/{objekt}
Vrací:
updatedobjectseznam aktualizovaných objektů
doctorarrayseznam id objektů / objekt doctor (lékaři dostupní uživateli)
documentarrayseznam id objektů / objekt file (dokumenty dostupné uživateli)
presentationarrayseznam id objektů / objekt presentation (prezentace dostupné uživateli)
slidearrayseznam id objektů / objekt slide (slidy dostupné uživateli)
filearrayseznam id objektů / objekt file (veškeré soubory dostupné uživateli)
deletedobjectseznam smazaných objektů
doctorarrayseznam id objektů doctor
documentarrayseznam id objektů file
presentationarrayseznam id objektů presentation
slidearrayseznam id objektů slide
filearrayseznam id objektů file
optvarsarraypole volitelných položek v detailu lékaře,
pokud nejsou změny, vrací se null
check_sync_timeintinterval kontroly synchronizace v hodinách (1-24h)
Struktura volitelné položky (optvars):
namestringnázev proměnné
typestringtyp proměnné (string|int|bool)
descrstringpopis pole ve fromuláři

příklad

GET /clipnote/1.0.1/sync HTTP/1.1
Cookie: SID=2de02b832676d1d45471016c736b3a6b
HTTP/1.1 200 OK
{updated:{doctor:[1,2,3], presentation:[2,3], slide:[2,3,4,5,6,8,10], file:[1,2,3,4,5,6,7,8,9], company:[1], user:[1]}}
GET /clipnote/1.0/sync?last_update=1339145207 HTTP/1.1
Cookie: SID=2de02b832676d1d45471016c736b3a6b
HTTP/1.1 200 OK
{updated:{doctor:[2,3], presentation:[], slide:[2], file:[], company:[], user:[]}, deleted:{doctor:[3,8],...}}
GET /clipnote/1.0/sync?last_update=1339145207&send_object=true HTTP/1.1
Cookie: SID=2de02b832676d1d45471016c736b3a6b
HTTP/1.1 200 OK
{updated:{doctor:[{id:2,name:"Pavel",lname:"Novák"}], presentation:[{id:1,title:"Adherence",...],...}, deleted:{doctor:[3,8],...}}
GET /clipnote/1.0/sync/file?last_update=1339145207&send_object=true HTTP/1.1
Cookie: SID=2de02b832676d1d45471016c736b3a6b
HTTP/1.1 200 OK
{updated:{file:[{id:2,name:"Logo Meditorial",url:"http://",...}]}, deleted:{file:[1,6]}}

syncUp

/clipnote/1.0.1/syncUp

post

Metoda ukládá objekty pomocí dat ve formátu JSON, který je v těle POST požadavku. Požadavek je pole objektů (ve stejné struktuře, jako v jeho definici).

Vrací seznam uložených objektů ve stejné struktuře.

Momentálně je podporován pouze objekt stats.

JSON parametry:
statsarray[nepovinný] pole objektů stats

příklad

POST /clipnote/1.0/sync HTTP/1.1
Cookie: SID=2de02b832676d1d45471016c736b3a6b
{"stats":[{"user":1,"presentation":1,"doctor":1,"date":1343132980,"completed":true,"slide_stats":[{"slide":1,"duration":10},{"slide":2,"duration":15,"newsletter":"yes"},{"slide":3,"duration":20}]},{"user":1,"presentation":2,"doctor":3,"date":1343132980,"completed":true,"slide_stats":[{"slide":4,"duration":10},{"slide":5,"duration":15,"newsletter":"yes"},{"slide":6,"duration":20}]}]}
HTTP/1.1 200 OK
{"stats":[{"id":4,"presentation":1,"doctor":1,"user":1,"completed":true,"date":1343132980,"slide_stats":[{"slide":"1","duration":"10"},{"slide":"2","duration":"15","newsletter":"yes"},{"slide":"3","duration":"20"}]},{"id":5,"presentation":2,"doctor":3,"user":1,"completed":true,"date":1343132980,"slide_stats":[{"slide":"4","duration":"10"},{"slide":"5","duration":"15","newsletter":"yes"},{"slide":"6","duration":"20"}]}]}

{objekt}

/clipnote/1.0.1/{objekt}

Každý objekt (doctor, file...) má metodu pro získání, vytvoření, editaci, nebo smazání. Přihlášený uživatel nemusí mít práva na všechny akce - v tomto případě se vrací kód 403. Neexistuje-li požadovaný objekt, vrací se 404.

get

Povinný parametr ID. Vrací vlastnosti objektu. Pokud neexistuje, vrací se kód 404

URL parametry:
idintid objektu
/clipnote/1.0.1/{objekt}/{id}
Vrací:
{objekt}objektobjekt požadovaného typu (doctor, file...)

post

Povinný parametr ID. Edituje data objektu. POST parametr obsahuje změněné vlastnosti podle struktury objektu. Ze struktury je vyjímáno ID a last_update, či další neměnné vlastnosti.

URL parametry:
idintid objektu
/clipnote/1.0.1/{objekt}/{id}
POST parametry:
změněné vlastnosti objektu, podle jeho struktury

put

Vytvoří nový objekt. POST parametr obsahuje vlastnosti podle struktury objektu. Ze struktury je vyjímáno ID a last_update, či další neměnné vlastnosti.

POST parametry:
vlastnosti objektu, podle jeho struktury
Vrací:
{objekt}objektvytvořený objekt

delete

Smaže objekt podle ID.

URL parametry:
idintid objektu
/clipnote/1.0.1/{objekt}/{id}

příklad

GET /clipnote/1.0/slide/2 HTTP/1.1
Cookie: SID=2de02b832676d1d45471016c736b3a6b
HTTP/1.1 200 OK
{id:2,title:"Welcome",files:[2,5,6],last_update:1339145207}
POST /clipnote/1.0.1/doctor/1 HTTP/1.1
Cookie: SID=2de02b832676d1d45471016c736b3a6b
fname=Jaroslav&email=jarda.novak@example.com
HTTP/1.1 200 OK
PUT /clipnote/1.0.1/doctor HTTP/1.1
Cookie: SID=2de02b832676d1d45471016c736b3a6b
ftitle=Mudr.&fname=Honza&lname=Lekarnik&office_street=Londýnská%2043&office_city=Praha&office_zip=12000
HTTP/1.1 200 OK
{id:2,ftitle:"Mudr.",fname:"Honza",....}
DELETE /clipnote/1.0.1/presentation/3 HTTP/1.1
Cookie: SID=2de02b832676d1d45471016c736b3a6b
HTTP/1.1 200 OK
GET /clipnote/1.0.1/slide/3 HTTP/1.1
Cookie: SID=2de02b832676d1d45471016c736b3a6b
HTTP/1.1 404 Not Found
DELETE /clipnote/1.0.1/file/10 HTTP/1.1
Cookie: SID=2de02b832676d1d45471016c736b3a6b
HTTP/1.1 403 Forbidden

Objekty

Datová struktura používaných objektů. Je uváděn název, datový typ (číslo v závorce znamená maximální délku) a popis proměnné. Text je vždy v kódování utf-8. Číselné typy budou obsahovat pouze čísla (případně desetinnou tečku u float).

Každý objekt má vlastní metodu pro získání, úpravu, vytvoření či smazání. Vlastnosti (kromě id, last_update) lze editovat, pokud není uveden opak.

user

Obsahuje data o uživateli ClipNote. Dostupné prezentace, dokumenty či lékaři se získají přes metodu sync.

Struktura:
idint
loginstring (20)přihlašovací jméno[nelze editovat]
fnamestring (30)jméno
lnamestring (50)příjmení
emailstring (60)email
langstring (2)jazyk uživatele (zkratka země)
companyobjektobjekt company[nelze editovat]
devbooloznačení developera
last_updatestringtimestamp poslední úpravy
{"id":1, "login":"mencl", "fname":"Marek", "lname":"Mencl", "email":"marek.mencl@meditorial.cz", "lang":"cz", "last_update":1339681814, "company":{"id":"1", "name":"Meditorial", "last_update":1340027207, "logo":"1"}, "dev":true}	

company

Struktura:
idint
namestring (30)název společnosti
logointid objektu file s logem společnosti (250x250)
logo_retinaintid objektu file s logem společnosti (retina, 500x500)
logo_smallintid objektu file s malým logem společnosti (400x400)
logo_small_retinaintid objektu file s malým logem společnosti (retina, 800x800)
last_updateinttimestamp poslední úpravy
{"id":1, "name":"Meditorial", "last_update":1340027207, "logo":1}	

file

Obsahuje informace o souborech dostupných pro reprezentanta, či používaných ve slidech. Soubor lze stáhnout přes klasický https protokol, ale musí být uveden SID v cookies - při požadavku na soubor může server vrátit 403, pokud přihlášený uživatel nemá na soubor práva.

Struktura:
idint
titlestring (50)titulek souboru
descrstring (100)popis souboru
file_namestring (50)název souboru[nelze editovat]
file_dirstring (20)adresář souboru[nelze editovat]
file_md5string (32)MD5 otisk souboru[nelze editovat]
urlstring (200)url ke stažení souboru[nelze editovat]
orderintřazení v seznamu dokumentů
last_updateinttimestamp poslední úpravy
{"id":1, "title":"Meditorial logo", "descr":"", "file_name":"meditorial.png", "file_dir":"logo", "last_update":1340028284, "url":"https:\/\/ssl.meditorial.cz\/clipnote-file\/logo\/meditorial.png"}

doctor

Struktura:
idint
ftitlestring (10)titul před jménem
fnamestring (30)jméno
lnamestring (50)příjmení
ltitlestring (10)titul za jménem
emailstring (60)email
phoneint (9)telefon
office_streetstring (50)ulice pracoviště
office_citystring (50)město pracoviště
office_zipint (5)PSČ pracoviště
office_latfloat (2.5)souřadnice zeměpisné šířky
office_lngfloat (3.5)souřadnice zeměpisné délky
last_updateinttimestamp poslední úpravy
historyarrayseznam spuštěných statistik u tohoto lékaře (jedná se o zkrácený objekt stats)
Struktura historie:
idint[nepovinný]
userintid objektu user reprezentant
presentationobjectzkrácená verze objektu presentation (viz. stats)
doctorintid objektu doctor, u kteréhého byla prováděna prezentacenabývá hodnoty null, pokud je spuštěna bez lékaře
dateinttimestamp spuštění prezentace
completedboolfalse, pokud byla prezentace ukončena před koncem
{"id":1, "ftitle":"MUDr.", "fname":"Monika", "lname":"\u010cern\u00e1", "ltitle":"", "office_street":"Soci\u00e1ln\u00ed p\u00e9\u010de 3316\/12a", "office_city":"\u00dast\u00ed nad Labem", "office_zip":40113, "office_lat":null, "office_lng":null, "email":"monika.cerna@mnul.cz", "phone":475682438, "last_update":1320929377}

presentation

Objekt obsahuje, kromě základních údajů, seznam veřejných a neveřejných slidů prezentace. Obě pole jsou řazeny podle skutečného pořadí v prezentaci, přičemž neveřejné slidy jsou vždy až za veřejnou částí.

Struktura:
idint
titlestring (50)název prezentace
descrstring (100)popis prezentace
slides_publicarraypole id objektů slide - veřejné slidy
slides_privatearraypole id objektů slide - neveřejné slidy (jen pro reprezanta)
loading_imageintid objektu file s loadovacím obrázkem
iconintid objektu file s ikonou prezentace (48x48)
icon_retinaintid objektu file s ikonou (retina, 96x96)
icon_smallintid objektu file s malou ikonou (25x25)
icon_small_retinaintid objektu file s malou ikonou (retina, 50x50)
orderintřazení v seznamu prezentací
last_updateinttimestamp poslední úpravy
{"id":1, "title":"Minirin", "descr":"", "last_update":1340097098, "icon":18, "slides_public":[1, 2], "slides_private":[]}

slide

Struktura:
idint
typestringnabývá hodnot public a private, indikuje, jestli se jedná o veřejný, nebo neveřejný slide
titlestring (50)název slidu
htmlintid objektu file s html souborem slidu
filesarraypole id objektů file využitých ve slidu
last_updateinttimestamp poslední úpravy
{"id":1, "type":"public", "title":"M1", "last_update":1340097239, "html":10, "files":[1, 2, 3, 4, 5, 6, 7, 9, 10, 12, 13, 14, 15, 16]}

stats

Objekt statistik. Obsahuje základní informace + hodnoty získané v průběhu prohlížení (values). Tyto hodnoty mají u každé prezentace jinou strukturu, ale vždy je to název - hodnota ve stringu.

Při ukládání statistik na server se neposílá parametr id a last_update.

Tento objekt nemá metodu pro úpravu (post).

Struktura:
idint[nepovinný]
userintid objektu user reprezentant
presentationobjectzkrácená verze objektu presentation spuštěné prezentace
doctorintid objektu doctor, u kteréhého byla prováděna prezentacenabývá hodnoty null, pokud je spuštěna bez lékaře
dateinttimestamp spuštění prezentace
user_latfloat (2.5)uživatelovi souřadnice zeměpisné šířky
user_lngfloat (3.5)uživatelovi souřadnice zeměpisné délky
app_versionstring (30)verze aplikace
completedboolfalse, pokud byla prezentace ukončena před koncem
durationintdélka prezentace v sekundách
presented_countintpočet odprezentovaných slidů
total_countintpočet slidů v prezentaci
slide_statsarraypole objektů s id slidů a dalšími daty v pořadí procházení prezentace
Struktura prezentace:
idint
titlestring (50)název prezentace
descrstring (100)popis prezentace
iconintid objektu file s ikonou prezentace (48x48)
icon_retinaintid objektu file s ikonou (retina, 96x96)
icon_smallintid objektu file s malou ikonou (25x25)
icon_small_retinaintid objektu file s malou ikonou (retina, 50x50)
last_updateinttimestamp poslední úpravy

Příklad objektu v poli slides:

data získaná klientem:
slide1id slidu
duration32doba strávená na slidu
data získaná slidem: (mění se slide od slidu, nemusí být žádné)
newsletteryes
patient_count10
patient_adherence35
{"id":120, "presentation":1, "doctor":3, "date":1340097039, "last_update":1340097239, "slides":[{"slide":1, "duration":10, "newsletter":"yes"},{"slide":2, "duration":28, "patient_adherence":"38"}]}

Statusové kódy

200OK
301Moved Permanentlyredirection of the resource to new url
400Bad Requestvalidation errors
401Unauthorizedauthentication errors
403Forbiddenauthorization errors
404Not Foundresource doesn’t exist on given url
405Method Not Allowedresource on given url doesn’t support this http method
409Conflictresource already exists
413Request too largerequest body is too large for processing (in file uploads)
500Internal errorserver failed to serve the request
503Service unavailableserver or some of its backends is down