wiki:RestfulAPIDevelopment
Last modified 6 years ago Last modified on 05/01/08 17:51:18

CKAN Restful API: Future Development

Suffers from a number of 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