]> dev.renevier.net Git - syp.git/blob - devdoc/api.txt
web interface to add co-administrators
[syp.git] / devdoc / api.txt
1 # feature definition
2
3 A feature represents a location. It has index _fid_. It has two dimensions:
4 _lagitude_ and _longitude_. It may have an image represented by it's url.
5 This field is called _imgurl_; it may also have a _title_ and/or a _description_.
6
7 # client to server communication:
8
9 Client submits a classic html form to server. 
10
11 **note**: In this documentation, php notation is used (`_POST` and `_FILES`),
12 but server may be written in any language.
13
14 ` _POST["password"]` and `_POST["user"] may contain user name and password. If
15  they are set, access is checked. If they is not set, cookies are checked. If
16  neither are present.
17
18 `_POST["request"]` is either:
19
20 ## auth
21  asks for authentication
22
23 ## newuser
24  adds a new user
25  * `$_POST ["newuser_name"]` must contain user name
26  * `$_POST ["newuser_password"]` must contain user password
27
28  Only admin can add new users.
29
30
31 ## add
32  adds a new feature
33
34  * `_POST["lon"]` must contain feature longitude
35  * `_POST["lat"]` must contain feature latitude
36  * `_POST["title"]` may contain feature title
37  * `_POST["description"]` may contain feature description
38  * `_FILES["image_file"]` may contain an uploaded image
39
40 ## del
41  to delete an existing feature
42
43  * `_POST["fid"]` must contain feature id
44
45 ## update
46  to modify an existing feature
47
48  * `_POST["fid"]` must contain feature id
49  * `_POST["lon"]` must contain feature longitude
50  * `_POST["lat"]` must contain feature latitude
51  * `_POST["title"]` may contain feature title
52  * `_POST["description"]` may contain feature description
53
54  if `_POST["keep_img"]` is "yes", feature image will not be modified.
55  Otherwise, `_FILES["photo_file"]` is checked for an uploaded file. If
56  `_FILES["photo_file"]` is empty, existing feature image will be deleted.
57  Otherwise, uploaded file will replace current feature image.
58
59 # server reply to client:
60 Server replies with xml content. In an ideal world, reply would be just xml
61 content. But due to technical issues, syp must wrap xml content in the body of a
62 html document. So for example, instead of sending 
63
64 `<error reason="unauthorized"></error>`
65
66 as _text/xml_, syp sends
67
68 `<html><head></head><body><error reason="unauthorized"></error></body></html>`
69
70 as _text/html_
71
72 ## error handling:
73
74  reply is something like `<error reason="?reason?"></error>` with _?reason?_ can be either:
75
76  * `unauthorized`: user is not authorized to execute request, or authentication failed
77  * `server`: an error occured on server side (such as database problem)
78  * `request`: server could not understand request
79  * `toobig`: uploaded file was too big
80  * `notation`: uploaded file was not an image
81  * `nochange`: when trying to update a feature, there is nothing to update (ie: no field of the feature has changed)
82  * `newuser_exists`: when trying to add an user which has the same name as an already registered user
83
84 ## success handling:
85
86  * `<success request="auth"><user>?user_name?</name></success>`:
87      authentication was successfull. ?user_name? is name of authenticated user.
88
89  * `<success request="newuser"><user>?user_name?</name></success>`:
90      new user addition was successfull. ?user_name? is name of newly added user.
91
92  * `<success request="del">
93      <feature>
94         <id>?id?</id>
95      </feature>
96     </success>`:
97      deletion was successfull. _?id?_ was property of deleted feature
98
99 *  `<success request="add">
100      <feature>
101        <id>?id?</id>
102        <imgurl>?imgurl?</imgurl>
103        <description>?description?</description>
104        <heading>?heading?</heading>
105        <lon>?lon?</lon>
106        <lat>?lat?</lat>
107      </feature>
108    </success>`:
109      addition was successfull. _?id?_, _?imgurl?_, _?description?_,
110      _?heading?_, _?lon?_, _?lat?_ are properties of added feature;
111
112 *  `<success request="update">
113       <feature>
114         <id>?id?</id>
115         <imgurl>?imgurl?</imgurl>
116         <description>?description?</description>
117         <heading>?heading?</heading>
118         <lon>?lon?</lon>
119         <lat>?lat?</lat>
120      </feature>
121    </success>`:
122      update was successfull. _?id?_, _?imgurl?_, _?description?_, _?heading?_,
123      _?lon?_, _?lat?_ are properties of updated feature;