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;