X-Git-Url: https://dev.renevier.net/gitweb.cgi?p=syp.git;a=blobdiff_plain;f=devdoc%2Fapi.txt;fp=devdoc%2Fapi.txt;h=cc1413e78b94de01a3009dff96e418787cc40302;hp=0000000000000000000000000000000000000000;hb=57511b4efd7402ef58de66ac1fe2c01ed1b1d7b5;hpb=cbcf49abc26fb050cadf77d8acedfd844ff94dbe
diff --git a/devdoc/api.txt b/devdoc/api.txt
new file mode 100644
index 0000000..cc1413e
--- /dev/null
+++ b/devdoc/api.txt
@@ -0,0 +1,109 @@
+# feature definition
+
+A feature represents a location. It has index _fid_. It has two dimensions:
+_lagitude_ and _longitude_. It may have an image represented by it's url.
+This field is called _imgurl_; it may also have a _title_ and/or a _description_.
+
+# client to server communication:
+
+Client submits a classic html form to server.
+
+**note**: In this documentation, php notation is used (`_POST` and `_FILES`),
+but server may be written in any language.
+
+`_POST["request"]` is either:
+
+## auth
+ asks for authentication
+
+ * ` _POST["password"]` must contains user password
+
+## add
+ adds a new feature
+
+ * `_POST["lon"]` must contain feature longitude
+ * `_POST["lat"]` must contain feature latitude
+ * `_POST["title"]` may contain feature title
+ * `_POST["description"]` may contain feature description
+ * `_FILES["image_file"]` may contain an uploaded image
+
+## del
+ to delete an existing feature
+
+ * `_POST["fid"]` must contain feature id
+
+## update
+ to modify an existing feature
+
+ * `_POST["fid"]` must contain feature id
+ * `_POST["lon"]` must contain feature longitude
+ * `_POST["lat"]` must contain feature latitude
+ * `_POST["title"]` may contain feature title
+ * `_POST["description"]` may contain feature description
+
+ if `_POST["keep_img"]` is "yes", feature image will not be modified.
+ Otherwise, `_FILES["photo_file"]` is checked for an uploaded file. If
+ `_FILES["photo_file"]` is empty, existing feature image will be deleted.
+ Otherwise, uploaded file will replace current feature image.
+
+# server reply to client:
+Server replies with xml content. In an ideal world, reply would be just xml
+content. But due to technical issues, syp must wrap xml content in the body of a
+html document. So for example, instead of sending
+
+``
+
+as _text/xml_, syp sends
+
+``
+
+as _text/html_
+
+## error handling:
+
+ reply is something like `` with _?reason?_ can be either:
+
+ * `unauthorized`: user is not authorized to execute request, or authentication failed
+ * `server`: an error occured on server side (such as database problem)
+ * `request`: server could not understand request
+ * `toobig`: uploaded file was too big
+ * `notation`: uploaded file was not an image
+ * `nochange`: when trying to update a feature, there is nothing to update (ie: no field of the feature has changed)
+
+## success handling:
+
+ * ``:
+ authentication was successfull
+
+ * `
+
+ ?id?
+
+ `:
+ deletion was successfull. _?id?_ was property of deleted feature
+
+* `
+
+ ?id?
+ ?imgurl?
+ ?description?
+ ?heading?
+ ?lon?
+ ?lat?
+
+ `:
+ addition was successfull. _?id?_, _?imgurl?_, _?description?_,
+ _?heading?_, _?lon?_, _?lat?_ are properties of added feature;
+
+* `
+
+ ?id?
+ ?imgurl?
+ ?description?
+ ?heading?
+ ?lon?
+ ?lat?
+
+ `:
+ update was successfull. _?id?_, _?imgurl?_, _?description?_, _?heading?_,
+ _?lon?_, _?lat?_ are properties of updated feature;