Ticket #1240 (assigned enhancement)

Opened 3 years ago

Last modified 2 years ago

[super] API v4

Reported by: rgrp Owned by: kindly
Priority: awaiting triage Milestone: ckan-backlog
Component: ckan Keywords:
Cc: Repository: ckan
Theme: none

Description (last modified by rgrp) (diff)

(Just creating this ticket as somewhere to keep notes)

  • Decide on REST api versus action API
    • Do we want to support both?
  • Tidying
    • Unify on /api/v{version num}/... structure (do we want a default option that points to current default? e.g. /api/default/ ...)
    • extras merged into normal field list in package
    • Get rid of /rest/ so just have api/v1/package
    • Get rid of separation of search api from 'rest' api
      • Propose that GET on REST index is search e.g. /package/?q=...
        • This is also resolves issue whereby GET at root returns whole package set (a *bad* idea) as this would now become the matchall search query (with a default limit on items returned)
  • Resource read/write in API (separate from package)
    • Does this need authorization work?
  • user/account API - read/write
  • Remove autocomplete -- can just use search
    • Do not worry about backwards compat as should only be used in our js (if others using it too bad!)

Change History

comment:1 Changed 3 years ago by rgrp

  • Summary changed from [super] API v3 to [super] API v4
  • Milestone changed from ckan-v1.5 to ckan-backlog

comment:2 Changed 3 years ago by dread

I basically agree, but just thought I'd add a couple of comments into the mix.

GET at root returns whole package set (a *bad* idea)

Sure it has a cost, but I don't see what the problem with this is if the list is cached. Forcing developers to paging through the list of packages is putting unnecessary obligations. I'd say that the top two RESTful operations are listing objects and getting a particular one, and you'd be taking away one of those.

Unify on /api/v{version num}/... structure

Where is it not currently unified?

comment:3 Changed 3 years ago by rgrp

  • Description modified (diff)

add autocomplete

comment:4 Changed 2 years ago by rgrp

  • Owner set to kindly
  • Status changed from new to assigned
  • Milestone changed from ckan-backlog to ckan-v1.6

assigning to kindly for review

comment:5 Changed 2 years ago by rgrp

  • Description modified (diff)

comment:6 Changed 2 years ago by dread

Although I'm generally in favour of Action API over RESTful, Action API does need some sorting out wrt listing methods, advertising what params are allowed and checking those that are passed. Using the Action API is so hard without reading the code!

The RESTful API is handy when you want to do something quickly in a browser. I'd not want to lose these two, for example:

  • to look at a package /api/rest/dataset/xyz
  • API version etc. at /api/util/status (coming with ckan 1.5.2)

It's also really handy in demos and to send as links to people on the list.

comment:7 Changed 2 years ago by rgrp

  • Milestone changed from ckan-v1.6 to ckan-backlog

IMO this is non-urgent and can move out of v1.6 as we have enough more important stuff to do.

Note: See TracTickets for help on using tickets.