Ticket #954 (closed enhancement: fixed)

Opened 3 years ago

Last modified 3 years ago

[super] API version 3

Reported by: rgrp Owned by: kindly
Priority: major Milestone: ckan-v1.5
Component: ckan Keywords:
Cc: Repository: ckan
Theme: none

Description (last modified by thejimmyg) (diff)

Child tickets:

  • #1107 Move package autocomplete from package controller and move to API
  • #1087 version and contact info api call

Move to a format that has a separate responseHeader and response.

A standard package response

{
  responseHeader: {
    status: 0,
  }    
  response: {package-dict}
}

On error:

{
  responseHeader: {
    status: {err-code},
    error: 'message'
  }    
  response: none
}

A search query

Based directly on solr.

{
  responseHeader: {
    status: 0,
  }    
  response: {
    numFound: 5,
    start: 0
    docs: [
    ]
  }
}

Issues

This is a breaking change for clients

References

Change History

comment:1 Changed 3 years ago by thejimmyg

  • Owner set to thejimmyg

I'll look at this for a v3 API with kindly as part of the dictization. It also addresses some potential XSS issues in the API we've discovered.

comment:2 Changed 3 years ago by thejimmyg

  • Repository set to ckan
  • Theme set to none

What would also be really nice is a help key in the response which was always returned unless a query parameter of ?help=False was sent.

The help text could explain what the response meant but more importantly would show examples of other calls you can make with the IDs returned such that the whole API is discoverable without anyone ever needing to read any docs! It also means the API documentation is more likely to be up to date since it will be obvious to developers when it isn't.

With help=False, the JSON can have all whitespace stripped too for production use.

I also think there should be no distinction between GET and POST so that people can easily link to API calls if they want to.

comment:3 Changed 3 years ago by thejimmyg

  • Milestone changed from ckan-v1.4 to ckan-v1.4-sprint-7

David Raznick has implemented JSON errors for the v1 and v2 API, we'll look at this over the next few weeks.

comment:4 Changed 3 years ago by thejimmyg

  • Summary changed from Change API JSON response format to include errors etc to API version 3
  • Milestone changed from ckan-v1.5 to ckan-backlog

See also this proposal about "inlining" extras fields #972.

David Raznick and I have also agreed that for API 3, each call to the logic layer will return an object (basically a dictionary) rather than using Exceptions. This means the return values from the logic layer can exactly mirror the JSON data strucutres returned via the API.

The help values can come from the docstrings of the logic layer functions.

comment:5 Changed 3 years ago by thejimmyg

  • Summary changed from API version 3 to [super] API version 3
  • Description modified (diff)
  • Milestone changed from ckan-backlog to ckan-v1.5

comment:6 Changed 3 years ago by dread

  • Owner changed from thejimmyg to kindly
  • Status changed from new to assigned

comment:7 Changed 3 years ago by rgrp

@kindly: can you update here. My impression is that lots was done but the current ticket description bears little relation to what was done. Suggest we move current content to a new ticket and update this with a short description of what *was* done and then close -- does this sound sensible?

comment:8 Changed 3 years ago by kindly

  • Status changed from assigned to closed
  • Resolution set to fixed

This is basically the complete now with documentation. The child tickets no longer seem to fit and are not essential for completion.

Note: See TracTickets for help on using tickets.