]> dev.renevier.net Git - syp.git/blob - devdoc/api.txt
bump version to 0.2
[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"]` may contains user password. If it is set, access is
15  checked. If it is not set, authentification cookie is checked. If neither are
16  present, or if one of them is wrong, access is denied.
17
18 `_POST["request"]` is either:
19
20 ## auth
21  asks for authentication
22
23 ## add
24  adds a new feature
25
26  * `_POST["lon"]` must contain feature longitude
27  * `_POST["lat"]` must contain feature latitude
28  * `_POST["title"]` may contain feature title
29  * `_POST["description"]` may contain feature description
30  * `_FILES["image_file"]` may contain an uploaded image
31
32 ## del
33  to delete an existing feature
34
35  * `_POST["fid"]` must contain feature id
36
37 ## update
38  to modify an existing feature
39
40  * `_POST["fid"]` must contain feature id
41  * `_POST["lon"]` must contain feature longitude
42  * `_POST["lat"]` must contain feature latitude
43  * `_POST["title"]` may contain feature title
44  * `_POST["description"]` may contain feature description
45
46  if `_POST["keep_img"]` is "yes", feature image will not be modified.
47  Otherwise, `_FILES["photo_file"]` is checked for an uploaded file. If
48  `_FILES["photo_file"]` is empty, existing feature image will be deleted.
49  Otherwise, uploaded file will replace current feature image.
50
51 # server reply to client:
52 Server replies with xml content. In an ideal world, reply would be just xml
53 content. But due to technical issues, syp must wrap xml content in the body of a
54 html document. So for example, instead of sending 
55
56 `<error reason="unauthorized"></error>`
57
58 as _text/xml_, syp sends
59
60 `<html><head></head><body><error reason="unauthorized"></error></body></html>`
61
62 as _text/html_
63
64 ## error handling:
65
66  reply is something like `<error reason="?reason?"></error>` with _?reason?_ can be either:
67
68  * `unauthorized`: user is not authorized to execute request, or authentication failed
69  * `server`: an error occured on server side (such as database problem)
70  * `request`: server could not understand request
71  * `toobig`: uploaded file was too big
72  * `notation`: uploaded file was not an image
73  * `nochange`: when trying to update a feature, there is nothing to update (ie: no field of the feature has changed)
74
75 ## success handling:
76
77  * `<success request="auth"></success>`:
78      authentication was successfull
79
80  * `<success request="del">
81      <feature>
82         <id>?id?</id>
83      </feature>
84     </success>`:
85      deletion was successfull. _?id?_ was property of deleted feature
86
87 *  `<success request="add">
88      <feature>
89        <id>?id?</id>
90        <imgurl>?imgurl?</imgurl>
91        <description>?description?</description>
92        <heading>?heading?</heading>
93        <lon>?lon?</lon>
94        <lat>?lat?</lat>
95      </feature>
96    </success>`:
97      addition was successfull. _?id?_, _?imgurl?_, _?description?_,
98      _?heading?_, _?lon?_, _?lat?_ are properties of added feature;
99
100 *  `<success request="update">
101       <feature>
102         <id>?id?</id>
103         <imgurl>?imgurl?</imgurl>
104         <description>?description?</description>
105         <heading>?heading?</heading>
106         <lon>?lon?</lon>
107         <lat>?lat?</lat>
108      </feature>
109    </success>`:
110      update was successfull. _?id?_, _?imgurl?_, _?description?_, _?heading?_,
111      _?lon?_, _?lat?_ are properties of updated feature;