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.
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
- Typos create queues? Could mitigate with an operation flag (lazy=True by default)
- 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.