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