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 ## 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"><user>?user_name?</name></success>`:
  78      authentication was successfull. ?user_name? is name of authenticated user.
  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;