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