Zaqar/specs/api/next

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

summary | log

• Auto-generate client UUID if not given
  • Makes things more confusing, since
• Clearly define whether client ID is required for every request, and enforce it in the implementation
  • Always require it, and log the id in every log line for tracing, analytics, support, etc.
  • Plan for v1.1
• Consider allowing opaque string for client ID rather than UUID (will need to understand what else people want to use?)
  • it isn't *that* hard to generate one
  • saying it has to be uuid makes validation easier, and reduces confusion
• Remove deprecated "partial results" semantics from message posting
  • This is no longer a possiblity with the mongo driver, and other backends probably don't need it either
  • Simplifies client implementations
  • Plan for v1.1
• Include claim information when listing messages and retrieving individual messages
  • Include Client ID in claim data
  • Helps when auditing a queue, diagnostics?
  • Extra storage is trivial when storing UUID as binary (16 bytes)
  • Plan tentatively for v1.1 - need to think more about use cases
• List claims for a given queue
  • Worker should be able to trust claim was created as expected
  • Other workers should not be looking at claims they did not create
  • Auditor client can list messages and see claim IDs on them if it wants to verify
• Automatically create queues the first time a message is posted to it
  • Revisit for v2.0
  • Metadata?
  • Typos create queues? Could mitigate with an operation flag (lazy=True by default)

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.