Usermap API

Changes for document Usermap API

Last modified by Jakub Jirůtka on 2015-03-13, 17:50
From version 2.1
edited by Jakub Jirůtka
on 2015-03-01, 17:19
To version 3.1
edited by Jakub Jirůtka
on 2015-03-01, 18:05
Change comment: There is no comment for this version

Content changes

... ... @@ -1,13 +1,106 @@
1 -Usermap API (pracovní název) je agregátor údajů o identitách lidí na ČVUT, který vyvíjíme na FIT. Poskytuje základní informace o osobě jako je jméno, uživatelské jméno, emailové adresy, telefony, … a tzv. byznys role (z IDM). Dále obsahuje informace o organizačních jednotkách ČVUT a místnostech (vč. adresy).
1 +Usermap API (pracovní název) je agregátor údajů o identitách lidí na ČVUT, který vyvíjíme na FIT. Poskytuje základní informace o osobě jako je jméno, uživatelské jméno, emailové adresy, telefony, … a tzv. byznys role (z IDM). Dále obsahuje informace o organizačních jednotkách ČVUT a místnostech (vč. adresy).
2 2
3 -== Primární datové zdroje ==
3 +## Primární datové zdroje
4 4
5 -Primárním zdrojem dat je Usermap (SSU), konkr. Usermap LDAP, jeho relační přívěšek EXT_UMAP a ještě webové rozhraní (fotky). Více informací o datové doméně Usermap najdete na [[této stránce>>https://rozvoj.fit.cvut.cz/Main/usermap-db]]. Dále se synchronizuje s fakultním IDM FIT, odkud se přebírají další fakultní role osob a identity externistů.
5 +Primárním zdrojem dat je Usermap (SSU), konkr. Usermap LDAP, jeho relační přívěšek EXT_UMAP a ještě webové rozhraní (fotky). Více informací o datové doméně Usermap najdete na [této stránce](https://rozvoj.fit.cvut.cz/Main/usermap-db). Dále se synchronizuje s fakultním IDM FIT, odkud se přebírají další fakultní role osob a identity externistů.
6 6
7 -== RESTful API ==
7 +## RESTful API
8 8
9 -Dokumentaci prvotní verze RESTového API zatím najdete na [[tady>>https://kosapi.fit.cvut.cz/usermap/doc/rest-api-v1.html]] (generované z [[RAML>>https://kosapi.fit.cvut.cz/usermap/doc/rest-api-v1.raml]]).
9 +Dokumentaci prvotní verze RESTového API zatím najdete [tady](https://kosapi.fit.cvut.cz/usermap/doc/rest-api-v1.html) (generované z [RAML](https://kosapi.fit.cvut.cz/usermap/doc/rest-api-v1.raml)).
10 10
11 -=== Zabezpečení ===
11 +API podporuje parametrické dotazy pomocí [RSQL](https://github.com/jirutka/rsql-parser/blob/master/README.md). Ke standardním operátorům přidává ještě operátor `=all=`; hodnota nebo kolekce hodnot musí obsahovat _všechny_ uvedené argumenty.
12 12
13 -API je zabezpečeno protokolem OAuth 2.0 a využívá [[fakultní autorizační server>>oauth2]].
13 +API je zabezpečeno protokolem OAuth 2.0 a využívá [fakultní autorizační server](oauth2).
14 +
15 +
16 +## Příklady
17 +
18 +### Dotazy přes curl
19 +
20 +Uvedené příklady využívají CLI utilitu [curl](http://curl.haxx.se/), lze však použít i libovolný jiný HTTP klient, vč. webového prohlížeče.
21 +
22 +1. Vypsat uživatele jirutjak (ve formátu JSON):
23 +
24 + ```sh
25 + curl -s -H 'Authorization: Bearer TOKEN' -H 'Accept: application/json' \
26 + 'https://kosapi.fit.cvut.cz/usermap/v1/people/jirutjak'
27 + ```
28 +
29 +2. Najít uživatele s uživatelským jménem jirutjak, spaceji3 a szolatib:
30 +
31 + ```sh
32 + curl -s -H 'Authorization: Bearer TOKEN' -H 'Accept: application/json' \
33 + 'https://kosapi.fit.cvut.cz/usermap/v1/people?query=username=in=(jirutjak,spaceji3,szolatib)'
34 + ```
35 +
36 +3. Najít uživatele, kteří mají role `B-18000-ZAMESTNANEC` a `B-00000-STUDENT`, _a zároveň_ nemají roli `B-18000-STUDENT`:
37 +
38 + ```sh
39 + curl -s -H 'Authorization: Bearer TOKEN' -H 'Accept: application/json' \
40 + 'https://kosapi.fit.cvut.cz/usermap/v1/people?query=roles=all=(B-81000-ZAMESTNANEC,B-00000-STUDENT);roles=out=(B-18000-STUDENT)'
41 + ```
42 +
43 +4. Najít uživatele, kteří mají role `B-18000-ZAMESTNANEC` a `B-00000-STUDENT`, _nebo_ `B-13000-ZAMESTNANEC` a `B-00000-STUDENT`:
44 +
45 + ```sh
46 + curl -s -H 'Authorization: Bearer TOKEN' -H 'Accept: application/json' \
47 + 'https://kosapi.fit.cvut.cz/usermap/v1/people?query=roles=all=(B-81000-ZAMESTNANEC,B-00000-STUDENT),roles=all=(B-82000-ZAMESTNANEC,B-00000-STUDENT)'
48 + ```
49 +
50 +5. Najít uživatele, kteří mají email `kevin.flynn@fit.cvut.cz`:
51 +
52 + ```sh
53 + curl -s -H 'Authorization: Bearer TOKEN' -H 'Accept: application/json' \
54 + 'https://kosapi.fit.cvut.cz/usermap/v1/people?query=emails==kevin.flynn@fit.cvut.cz'
55 + ```sh
56 +
57 +6. Najít uživatele, jejichž jméno/příjmení začíná na Eli Šes a studují na FIT:
58 +
59 + ```sh
60 + curl -s -H 'Authorization: Bearer TOKEN' -H 'Accept: application/json' \
61 + -G 'https://kosapi.fit.cvut.cz/usermap/v1/people' --data-urlencode 'query=name=="Eli Šes";roles==B-18000-STUDENT'
62 + ```
63 +#[warning](curl špatně enkóduje některé znaky v URI, tady uvozovky a mezera, proto je nutné předat query string přes `--data-urlencode`.)
64 +
65 +7. Vypsat detaily role `B-18000-ZAMESTNANEC`:
66 +
67 + ```sh
68 + curl -s -H 'Authorization: Bearer TOKEN' -H 'Accept: application/json' \
69 + https://kosapi.fit.cvut.cz/usermap/v1/roles/B-18000-ZAMESTNANEC
70 + ```
71 +
72 +Pozor na to, že výstup je stránkovaný; výchozí hodnota je 10 záznamů. Pro zvýšení limitu slouží URI parametr `limit`, pro určení prvního záznamu parametr `offset`.
73 +Například pro získání 100 záznamů, počínaje padesátým:
74 +
75 +```sh
76 +https://kosapi.fit.cvut.cz/usermap/v1/people?roles==B-18000-STUDENT&offset=50&limit=100
77 +```
78 +
79 +### Parsování JSON z příkazové řádky
80 +
81 +Pro pohodlné parsování JSONu v shellu lze použít například nástroj [jq](https://github.com/stedolan/jq).
82 +Výstup z curlu je možné do něj poslat přímo přes _pipu_.
83 +
84 +1. Vypsání celého jména jednoho uživatele:
85 +
86 + ```sh
87 + jq -r '. | .fullName'
88 + ```
89 +
90 +2. Vypsání celého jména více uživatelů v kolekci:
91 +
92 + ```sh
93 + jq -r '.[] | .fullName'
94 + ```
95 +
96 +3. Vypsání všech rolí jednoho uživatele jako seznam oddělený novou řádkou:
97 +
98 + ```sh
99 + jq -r '. | .roles | join("\n")'
100 + ```
101 +
102 +4. Vypsání uživatelského jména, celého jména a preferovaného emailu kolekce uživatelů jako CSV:
103 +
104 + ```sh
105 + jq -r '.[] | [.username, .fullName, .preferredEmail ] | @csv'
106 + ```

My Recent Modifications


This wiki is licensed under a Creative Commons BY-SA 3.0 license
XWiki Enterprise 5.4.1 - Documentation