Changes between Initial Version and Version 1 of RestfulAPIDevelopment

Timestamp:

05/01/08 17:51:18 (6 years ago)

Author:

rgrp

Comment:

move future development and original proposal stuff here from RestfulAPI

RestfulAPIDevelopment

@@ +1 @@
+= CKAN Restful API: Future Development =
+
+Suffers from a number of [http://www.prescod.net/rest/mistakes/ RESTful no-no's]....
+
+== Design Questions ==
+
+ * What are the resources, and where are they located?
+ * What data formats are in use?
+ * What methods are supported at each resource location?
+ * What status codes could be returned?
+
+== Current Development Issues ==
+
+ * How does a machine client acquire and select from the package license options?
+ * Can the above POST parameter data types be specified more formally?
+
+----
+
+= Original API Proposal =
+
+== Resources ==
+
+|| '''Resource''' || '''Location''' ||
+|| All Licenses|| !http://ckan.net/api/rest/licenses ||
+|| Licence || !http://ckan.net/api/rest/license/:id ||
+|| All Packages || !http://ckan.net/api/rest/packages ||
+|| Package || !http://ckan.net/api/rest/package/:id ||
+|| All Tags || !http://ckan.net/api/rest/tags ||
+|| Tag || !http://ckan.net/api/rest/tag/:id ||
+
+== Data Formats ==
+
+''Todo: Decide how to identify objects (name, database ID, UUID), then fixup these data formats. Currently assumed to use the value of the object name attribute as the object's resource identifier.''
+
+==== Database ID Format ====
+
+{{{
+    An integer.
+}}}
+
+==== UUID Format ====
+
+{{{
+    ?
+}}}
+
+
+==== Name ID Format ====
+
+{{{
+    The value of the object's name attribute.
+}}}
+
+
+==== License List Format ====
+
+{{{
+{
+    "licence-list": [
+        {
+            "id": "BSD"
+
+        },{
+            "id": "MIT"
+        }
+    ]
+}
+}}}
+
+==== License Format ====
+
+{{{
+{
+    "licence": {
+        "name": "BSD"
+    }
+}
+}}}
+
+==== Package List Format ====
+
+{{{
+{
+    "package-list": [
+        {
+            "id": "dataset-1"
+
+        },{
+            "id": "dataset-2"
+        }
+    ]
+}
+}}}
+
+==== Package Format ====
+
+{{{
+{
+    "package": {
+        "name": "dataset-1",
+        "title": "My Title",
+        "url": "http://mylocation",
+        "download_url": "http://mydownloadlocation",
+        "licences": [5,7],
+        "tags": "this that other",
+        "notes": "Some notes."
+    }
+}
+}}}
+
+==== Tag List Format ====
+
+{{{
+{
+    "tag-list": [
+        {
+            "id": "this"
+
+        },{
+            "id": "that"
+        }
+    ]
+}
+}}}
+
+==== Tag Format ====
+
+{{{
+{
+    "tag": {
+        "name": "this"
+    }
+}
+}}}
+
+== Methods, Formats, and Status Codes ==
+ 
+|| '''Resource''' || '''Method''' || '''Format''' || '''Status Codes''' ||
+|| All Licenses || GET || License List Format || 200, 301 ||
+|| All Licenses || POST || License Format || 201, 400 ||
+|| License || GET || License Format || 200, 301, 410 ||
+|| License || PUT || License Format || 200, 301, 400, 410 ||
+|| License || DELETE || N/A || 200, 204 ||
+|| All Packages || GET || Package List Format || 200, 301 ||
+|| All Packages || POST || Package Format || 201, 400 ||
+|| Package || GET || Package Format || 200, 301, 410 ||
+|| Package || PUT || Package Format || 200, 301, 400, 410 ||
+|| Package || DELETE || N/A || 200, 204 ||
+|| All Tags || GET || Tag List Format || 200, 301 ||
+|| All Tags || POST || Tag Format || 201, 400 ||
+|| Tags || GET || Tag Format || 200, 301, 410 ||
+|| Tags || PUT || Tag Format || 200, 301, 400, 410 ||
+|| Tags || DELETE || N/A || 200, 204 ||
+