]> dev.renevier.net Git - syp.git/blob - devdoc/api.txt
fixes notices
[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`,  `_FILES` and
12  `_COOKIE`), 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. If access is correct, cookies are set.
17
18 Alternatively, `_COOKIE["syp_user"]` and `_COOKIE["syp_auth"]` may contain user
19  name and md5 of password. If tables prefix is not *syp_*, cookies name are
20  modifier accordingly.
21
22 `_POST["request"]` is either:
23
24 ## auth
25  asks for authentication
26
27 ## changepass
28  change user password
29
30  * `_POST ["pass_current"]` must contain current password. This is needed: cookie
31     authentification is not enough.
32  * `_POST ["pass_new"]` must contain new password
33
34 ## newuser
35  adds a new user
36
37  * `_POST ["newuser_name"]` must contain user name
38  * `_POST ["newuser_password"]` must contain user password
39
40  **Only admin can add new users.**
41
42
43 ## add
44  adds a new feature
45
46  * `_POST["lon"]` must contain feature longitude
47  * `_POST["lat"]` must contain feature latitude
48  * `_POST["title"]` may contain feature title
49  * `_POST["description"]` may contain feature description
50  * `_FILES["image_file"]` may contain an uploaded image
51
52 ## del
53  to delete an existing feature
54
55  * `_POST["fid"]` must contain feature id
56
57 ## update
58  to modify an existing feature
59
60  * `_POST["fid"]` must contain feature id
61  * `_POST["lon"]` must contain feature longitude
62  * `_POST["lat"]` must contain feature latitude
63  * `_POST["title"]` may contain feature title
64  * `_POST["description"]` may contain feature description
65
66  if `_POST["keep_img"]` is "yes", feature image will not be modified.
67  Otherwise, `_FILES["photo_file"]` is checked for an uploaded file. If
68  `_FILES["photo_file"]` is empty, existing feature image will be deleted.
69  Otherwise, uploaded file will replace current feature image.
70
71 # server reply to client:
72 Server replies with xml content. In an ideal world, reply would be just xml
73 content. But due to technical issues, syp must wrap xml content in the body of a
74 html document. So for example, instead of sending 
75
76 `<error reason="unauthorized"></error>`
77
78 as _text/xml_, syp sends
79
80 `<html><head></head><body><error reason="unauthorized"></error></body></html>`
81
82 as _text/html_
83
84 ## error handling:
85
86  reply is something like `<error reason="?reason?"></error>` with _?reason?_ can be either:
87
88  * `unauthorized`: user is not authorized to execute request, or authentication failed
89  * `server`: an error occured on server side (such as database problem)
90  * `request`: server could not understand request
91  * `toobig`: uploaded file was too big
92  * `notation`: uploaded file was not an image
93  * `nochange`: when trying to update a feature, there is nothing to update (ie: no field of the feature has changed)
94  * `wrongpass`: wrong current password when trying to change password
95  * `newuser_exists`: when trying to add an user which has the same name as an already registered user
96
97 ## success handling:
98
99  * `<success request="auth"><user>?user_name?</name></success>`:
100      authentication was successfull. ?user_name? is name of authenticated user.
101
102  * `<success request="newuser"><user>?user_name?</name></success>`:
103      new user addition was successfull. ?user_name? is name of newly added user.
104
105  * `<success request="changepass"><user>?user_name?</name></success>`:
106      password change was successfull. ?user_name? is name user whose password
107      has been changed.
108
109  * `<success request="del">
110      <feature>
111         <id>?id?</id>
112      </feature>
113     </success>`:
114      deletion was successfull. _?id?_ was property of deleted feature
115
116 *  `<success request="add">
117      <feature>
118        <id>?id?</id>
119        <imgurl>?imgurl?</imgurl>
120        <description>?description?</description>
121        <heading>?heading?</heading>
122        <lon>?lon?</lon>
123        <lat>?lat?</lat>
124      </feature>
125    </success>`:
126      addition was successfull. _?id?_, _?imgurl?_, _?description?_,
127      _?heading?_, _?lon?_, _?lat?_ are properties of added feature;
128
129 *  `<success request="update">
130       <feature>
131         <id>?id?</id>
132         <imgurl>?imgurl?</imgurl>
133         <description>?description?</description>
134         <heading>?heading?</heading>
135         <lon>?lon?</lon>
136         <lat>?lat?</lat>
137      </feature>
138    </success>`:
139      update was successfull. _?id?_, _?imgurl?_, _?description?_, _?heading?_,
140      _?lon?_, _?lat?_ are properties of updated feature;