Jump to: navigation, search

Zaqar/specs/api/next

< Zaqar
Revision as of 18:12, 24 October 2013 by Kgriffs (talk | contribs) (HTTP)

Marconi API - Next

Brainstorming page for API improvements. The ideas below need to be discussed with the Marconi team and the OS community. They will be turned into blueprints as appropriate.

Generic

  • Auto-generate client UUID if not given
  • Clearly define whether client ID is required for every request, and enforce it in the implementation
  • Consider allowing opaque string for client ID rather than UUID (will need to understand what else people want to use?)
  • Remove deprecated "partial results" semantics from message posting
  • Include Client ID in claim data
  • Include claim information when listing messages and retrieving individual messages
  • List claims for a given queue

HTTP

  • Return an href for deleting all claimed messages with a single call
  • Allow PUTing metadata when creating a queue
  • 204 vs. 200 + empty array
  • Consistency around response envelope for /messages vs /messages?ids
  • Return full URIs in location/content-location headers (rather than relative ones)
  • Is content-location header really necessary?
  • Polling model is based on the assumption of a "streaming" interaction model. Is there a place for a "point in time" listing model, where you don't always get a "next" href?
  • Query parameters are usually considered to be "optional", and yet DELETE queues/my-queue/messages requires an "ids" parameter. Some options:
    • Make "ids" optional. In this case, DELETE my-queue/messages would be defined to delete all messages in the queue. See also: https://blueprints.launchpad.net/marconi/+spec/flush-queue
    • Allow lists of id’s in the path, such as my-queue/messages/1,2,3. We experimented with this is an early API draft, but a lot of people thought it looked strange/unusual, so we didn’t do it.
    • Don’t support bulk DELETE operations on messages.