[super] API version 3

[rgrp]

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

• ​http://wiki.apache.org/solr/SolJSON
• ​http://www.flickr.com/services/api/response.json.html

[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.

[thejimmyg]

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.

[thejimmyg]

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

[thejimmyg]

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.