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