Changes between Version 10 and Version 11 of RestfulAPI


Ignore:
Timestamp:
02/15/08 19:25:25 (6 years ago)
Author:
johnbywater
Comment:

Written proposal for a better CKAN REST API

Legend:

Unmodified
Added
Removed
Modified

  • RestfulAPI

    v10 v11  
    77 * What methods are supported at each URI? 
    88 * What status codes could be returned? 
     9 
     10---- 
     11 
     12= Current API = 
    913 
    1014== URLs == 
    … …  
    2024|| '''Response''' || JSON || 
    2125 
    22 == Methods == 
    23   
    24 || '''Action''' || '''Methods''' ||  
    25 || list || GET || 
    26 || create || POST || 
    27 || update || POST || 
    28 || read || GET || 
    29  
    30 == Status Codes == 
    31   
    32 || '''Action-Method''' || '''Success''' || '''Exception''' || 
    33 || list GET || 200 || 400 Invalid Request, 404 Not Found || 
    34 || create POST || 200 || 400 Invalid Request, 409 Conflict || 
    35 || update POST || 200 || 400 Invalid Request || 
    36 || read GET || 200 || 404 Not Found || 
    37  
    38 ---- 
    39  
    40 === POST Method Params === 
     26== POST Method Params == 
    4127 
    4228==== Create POST ==== 
    … …  
    5743|| log_message || string || 
    5844 
     45 
     46== Methods == 
     47  
     48|| '''Action''' || '''Methods''' ||  
     49|| list || GET || 
     50|| create || POST || 
     51|| update || POST || 
     52|| read || GET || 
     53 
     54== Status Codes == 
     55  
     56|| '''Action-Method''' || '''Success''' || '''Exception''' || 
     57|| list GET || 200 || 400 Invalid Request, 404 Not Found || 
     58|| create POST || 200 || 400 Invalid Request, 409 Conflict || 
     59|| update POST || 200 || 400 Invalid Request || 
     60|| read GET || 200 || 404 Not Found || 
     61 
     62 
    5963---- 
    6064 
    … …  
    6367 * How does a machine client acquire and select from the package license options? 
    6468 * Can the above POST parameter data types be specified more formally? 
     69 
     70---- 
     71 
     72= Proposed REST API = 
     73 
     74== Resources == 
     75 
     76|| '''Resource''' || '''Location''' || 
     77|| All Licenses|| !http://ckan.net/api/rest/licenses || 
     78|| Licence || !http://ckan.net/api/rest/license/:id || 
     79|| All Packages || !http://ckan.net/api/rest/packages || 
     80|| Package || !http://ckan.net/api/rest/package/:id || 
     81|| All Tags || !http://ckan.net/api/rest/tags || 
     82|| Tag || !http://ckan.net/api/rest/tag/:id || 
     83 
     84== Data Formats == 
     85 
     86==== License List Format ==== 
     87 
     88{{{ 
     89{ 
     90    "licence-list": [ 
     91        { 
     92            "id": 1, 
     93            'name": "BSD" 
     94 
     95        },{ 
     96            "id": 2, 
     97            "name": "MIT" 
     98        } 
     99    ] 
     100} 
     101}}} 
     102 
     103==== License Format ==== 
     104 
     105{{{ 
     106{ 
     107    "licence": { 
     108        "id": 1, 
     109        "name": "BSD" 
     110    } 
     111} 
     112}}} 
     113 
     114==== Package List Format ==== 
     115 
     116{{{ 
     117{ 
     118    "package-list": [ 
     119        { 
     120            "id": 1, 
     121            "name": "dataset-1" 
     122 
     123        },{ 
     124            "id": 2, 
     125            "name": "dataset-2" 
     126        } 
     127    ] 
     128} 
     129}}} 
     130 
     131==== Package Format ==== 
     132 
     133{{{ 
     134{ 
     135    "package": { 
     136        "id": 1, 
     137        "name": "string", 
     138        "title": "string", 
     139        "url": "string", 
     140        "download_url": "string", 
     141        "licences": [5,7], 
     142        "tags": "this that other", 
     143        "notes": "some notes" 
     144    } 
     145} 
     146}}} 
     147 
     148==== Tag List Format ==== 
     149 
     150{{{ 
     151{ 
     152    "tag-list": [ 
     153        { 
     154            "id": 1, 
     155            "name": "this" 
     156 
     157        },{ 
     158            "id": 2, 
     159            "name": "that" 
     160        } 
     161    ] 
     162} 
     163}}} 
     164 
     165==== Tag Format ==== 
     166 
     167{{{ 
     168{ 
     169    "tag": { 
     170        "id": 1, 
     171        "name": "this" 
     172    } 
     173} 
     174}}} 
     175 
     176== Methods and Status Codes == 
     177  
     178|| '''Resource''' || '''Method''' || '''Format''' || '''Status Codes''' || 
     179|| All Licenses || GET || License List Format || 200, 301 || 
     180|| All Licenses || POST || License Format || 201, 400 || 
     181|| License || GET || License Format || 200, 301, 410 || 
     182|| License || PUT || License Format || 200, 301, 400, 410 || 
     183|| License || DELETE || N/A || 200, 204 || 
     184|| All Packages || GET || Package List Format || 200, 301 || 
     185|| All Packages || POST || Package Format || 201, 400 || 
     186|| Package || GET || Package Format || 200, 301, 410 || 
     187|| Package || PUT || Package Format || 200, 301, 400, 410 || 
     188|| Package || DELETE || N/A || 200, 204 || 
     189|| All Tags || GET || Tag List Format || 200, 301 || 
     190|| All Tags || POST || Tag Format || 201, 400 || 
     191|| Tags || GET || Tag Format || 200, 301, 410 || 
     192|| Tags || PUT || Tag Format || 200, 301, 400, 410 || 
     193|| Tags || DELETE || N/A || 200, 204 || 
     194