Changes between Version 16 and Version 17 of RestfulAPI


Ignore:
Timestamp:
05/01/08 17:54:44 (6 years ago)
Author:
rgrp
Comment:

Make into a page containing only for API users only (Future development and original proposal info has been moved to separate page and some refactoring)

Legend:

Unmodified
Added
Removed
Modified

  • RestfulAPI

    v16 v17  
    11= The CKAN RESTful API = 
    2  
    3 == Design Questions == 
    4  
    5  * What are the resources, and where are they located? 
    6  * What data formats are in use? 
    7  * What methods are supported at each resource location? 
    8  * What status codes could be returned? 
    9  
    10 ---- 
    11  
    12 = Current API = 
    13  
    14 Suffers from a number of [http://www.prescod.net/rest/mistakes/ RESTful no-no's].... 
    152 
    163== URIs == 
    174 
    18  * !http://ckan.net/api/rest/package/list/:page 
     5 * !http://ckan.net/api/rest/package/list 
    196 * !http://ckan.net/api/rest/package/create/:name 
    207 * !http://ckan.net/api/rest/package/update/:name 
    218 * !http://ckan.net/api/rest/package/read/:name 
     9 
     10e.g. to get a list of all packages on CKAN visit: 
     11 
     12http://www.ckan.net/api/rest/package/list 
    2213 
    2314== Data Formats == 
    … …  
    2819== POST Method Params == 
    2920 
    30 ==== Create POST ==== 
     21=== Create POST === 
    3122 
    3223|| '''Name''' || '''Value''' || 
    3324|| name || lower case  alphanumeric string, optionally with dashes and underscores, string length at least 2 characters || 
    3425 
    35 ==== Update POST ==== 
     26=== Update POST === 
    3627 
    3728|| '''Name''' || '''Value''' || 
    … …  
    6253|| read GET || 200 || 404 Not Found || 
    6354 
    64  
    65 ---- 
    66  
    67 == Current Development Issues == 
    68  
    69  * How does a machine client acquire and select from the package license options? 
    70  * Can the above POST parameter data types be specified more formally? 
    71  
    72 ---- 
    73  
    74 = Proposed API = 
    75  
    76 == Resources == 
    77  
    78 || '''Resource''' || '''Location''' || 
    79 || All Licenses|| !http://ckan.net/api/rest/licenses || 
    80 || Licence || !http://ckan.net/api/rest/license/:id || 
    81 || All Packages || !http://ckan.net/api/rest/packages || 
    82 || Package || !http://ckan.net/api/rest/package/:id || 
    83 || All Tags || !http://ckan.net/api/rest/tags || 
    84 || Tag || !http://ckan.net/api/rest/tag/:id || 
    85  
    86 == Data Formats == 
    87  
    88 ''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.'' 
    89  
    90 ==== Database ID Format ==== 
    91  
    92 {{{ 
    93     An integer. 
    94 }}} 
    95  
    96 ==== UUID Format ==== 
    97  
    98 {{{ 
    99     ? 
    100 }}} 
    101  
    102  
    103 ==== Name ID Format ==== 
    104  
    105 {{{ 
    106     The value of the object's name attribute. 
    107 }}} 
    108  
    109  
    110 ==== License List Format ==== 
    111  
    112 {{{ 
    113 { 
    114     "licence-list": [ 
    115         { 
    116             "id": "BSD" 
    117  
    118         },{ 
    119             "id": "MIT" 
    120         } 
    121     ] 
    122 } 
    123 }}} 
    124  
    125 ==== License Format ==== 
    126  
    127 {{{ 
    128 { 
    129     "licence": { 
    130         "name": "BSD" 
    131     } 
    132 } 
    133 }}} 
    134  
    135 ==== Package List Format ==== 
    136  
    137 {{{ 
    138 { 
    139     "package-list": [ 
    140         { 
    141             "id": "dataset-1" 
    142  
    143         },{ 
    144             "id": "dataset-2" 
    145         } 
    146     ] 
    147 } 
    148 }}} 
    149  
    150 ==== Package Format ==== 
    151  
    152 {{{ 
    153 { 
    154     "package": { 
    155         "name": "dataset-1", 
    156         "title": "My Title", 
    157         "url": "http://mylocation", 
    158         "download_url": "http://mydownloadlocation", 
    159         "licences": [5,7], 
    160         "tags": "this that other", 
    161         "notes": "Some notes." 
    162     } 
    163 } 
    164 }}} 
    165  
    166 ==== Tag List Format ==== 
    167  
    168 {{{ 
    169 { 
    170     "tag-list": [ 
    171         { 
    172             "id": "this" 
    173  
    174         },{ 
    175             "id": "that" 
    176         } 
    177     ] 
    178 } 
    179 }}} 
    180  
    181 ==== Tag Format ==== 
    182  
    183 {{{ 
    184 { 
    185     "tag": { 
    186         "name": "this" 
    187     } 
    188 } 
    189 }}} 
    190  
    191 == Methods, Formats, and Status Codes == 
    192   
    193 || '''Resource''' || '''Method''' || '''Format''' || '''Status Codes''' || 
    194 || All Licenses || GET || License List Format || 200, 301 || 
    195 || All Licenses || POST || License Format || 201, 400 || 
    196 || License || GET || License Format || 200, 301, 410 || 
    197 || License || PUT || License Format || 200, 301, 400, 410 || 
    198 || License || DELETE || N/A || 200, 204 || 
    199 || All Packages || GET || Package List Format || 200, 301 || 
    200 || All Packages || POST || Package Format || 201, 400 || 
    201 || Package || GET || Package Format || 200, 301, 410 || 
    202 || Package || PUT || Package Format || 200, 301, 400, 410 || 
    203 || Package || DELETE || N/A || 200, 204 || 
    204 || All Tags || GET || Tag List Format || 200, 301 || 
    205 || All Tags || POST || Tag Format || 201, 400 || 
    206 || Tags || GET || Tag Format || 200, 301, 410 || 
    207 || Tags || PUT || Tag Format || 200, 301, 400, 410 || 
    208 || Tags || DELETE || N/A || 200, 204 || 
    209