API v4

Let's talk about what should be fixed in the next revision of the CKAN API.

Our action API (a JSON RPC-style API) maps directly to action functions. It is easy for core developers to maintain, and will always be complete. It also supports GET query parameter, JSON data and multipart fields with file uploads in much the same way. This makes it really simple to use with just curl or by keying values into a web browser location bar.

However using the values passed and returned is challenging for end users. Returned values are often nested and include computed data at multiple levels. Passed values may be ignored, optional or required (treated as blank even when not passed) These values map to what is convenient for the controllers we use for the web site, not what might make the most sense for an API.

Building a new REST API is an obvious choice, but any large layer in front of the action functions is difficult to maintain. How could this layer be kept as small as possible?

If you could have a new CKAN API, what would it look like, and how would it be better than what we have now?

The issue names no files or tests, only CKAN's existing action API and action functions; start by locating those entry points and documenting their current inputs and outputs. Done would require an agreed API v4 design that addresses the stated usability and maintenance concerns, rather than an isolated code change.

Written by the indexing model from the issue text.