Register/Update a package via a web-api

[johnbywater]

As A

User

I want To

Create/register and update a package via a web api.

[rgrp]

In many ways everything that is needed is already in place in that the package update and create controller just require raw posts to do their work. However should implement some kind of authentication/authorization to prevent automated spamming.

This would also require some way of distinguishing posts from our own WUI and those coming from outside (at present no checking is performed and the 'post' to these controllers is freely allowed by anyone out there!

[rgrp]

Methods potentially in need of access control at present (on controllers/package.py)

• update (_update)
• create

Frankly, for time being we can probably leave these unsecured but with monitoring. Should they be abused we can add access control fairly easily. So decision: no work on access control/auth for time being here.

Focus instead should be on:

• documentation of post parameters (rgrp)
• returning restful status values (201 Created, 204 Updated, etc)
• returning machine readable output from read and list (json)

[johnbywater]

So, after reading all about REST interfaces, I've written a functional requirement for a RESTfull interface to a web application domain model:

​http://desire.appropriatesoftware.net/requirements/60/

Basically, the 'fit criteria' require answers to these questions:

• What are the URIs?
• What's the format?
• What methods are supported at each URI?
• What status codes could be returned?

I think we can hope to make a clean rest interface at (something like) ckan.net/api/rest. Having such a distinct location is fairly common (cf. flickr.com) and prevents any clutering the web browser client interface with aspects of machine client support.

To make this point clearer, as RESTfullness claims to describe the web as it is, then the existing web browser interface must already be RESTfull. Hence, the main distinction with CKAN development is between CKAN's RESTfull machine interface and CKAN's RESTfull web browser client interface.

Hence, if a CKAN machine client will follow the client-server interaction of a CKAN web browser client, the main requirement is to make sure the format of the responses is client-appropriate. Whilst machine clients can make POST and GET requests in the same way as a web browsers, clearly machine clients don't need lots of decorative HTML when accessing domain objects.

Therefore, CKAN needs first to make user of a data format for rendering domain objects, and it needs to detect when it is required to return data in this format.

Options for data format are bascially XML or JSON. It looks like JSON is preferable.

Options for detecting client type are to prefix normal resource path with /api/rest/ or for the machine clients to pass a format=json parameter with each request.

[johnbywater]

So for this ticket, a REST interface for packages would involve:

See this wiki page for more information.

[rgrp]

The remaining issue is authentication. Initially was hopeful that we could use openid (perhaps with oauth) but this does not seem possible (despite much talk of openid and oauth being complementary) ... Thus we shall adopt this old-fashioned approach.

• A user who wishes to use the web api must obtain a web api key. They do this by:
  • Going to ckan.net and signing in using their open id.
  • Visit /account/apikey/: this should generate them a unique uuid key (or show their existing key if they already have one). This key should then be stored in the db along with their openid.
• Once a user has an api key they must include in the request when making changes. This may necessitate an update to the restful api to start having a more generic message format (this also makes it more extensible for the future):
  • auth: auth key
  • data: data body (what we currently send)

[rgrp]

Massive ticket now thoroughly addressed (early start in r242 and ff. then later in r275, r276 etc). Also now have start of demo ckan REST client at browser:ckanclient