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;