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