Jump to: navigation, search

Difference between revisions of "Zaqar/specs/api/v1/marconi-config"

(Description)
 
(11 intermediate revisions by one other user not shown)
Line 19: Line 19:
  
 
This variable controls:
 
This variable controls:
* The max integral value of the URI parameter "limit" a client can use in a [[Marconi/specs/api/v1#List_Queues]] request URI, thus, the maxinum number of queues a client can expect in the response's JSON array.  The default value is 20, which means, a request like the following:
+
* The max integral value of the URI parameter <code>limit</code> a client can use in a [[Marconi/specs/api/v1#List Queues]] request URI, thus, the maximum number of queues a client can list one time.  The default value is 20, which means, a request like the following:
  
  GET /v1/queues?limit=30
 
  
will result in '''400 Bad Request''' response.
+
GET /v1/queues?limit=30
 +
 
 +
will result in a '''400 Bad Request''' response.
  
 
<tt>message_paging_uplimit</tt>
 
<tt>message_paging_uplimit</tt>
  
This variable controls the following API endpoints:
+
This variable controls the following API limits:
* The maxinum number of messages a client can send in a [[Marconi/specs/api/v1#Post_Message(s)]] request's JSON array.  The default value is 20, which means, a request like the following:
+
* The maximum items a client can put in a [[Marconi/specs/api/v1#Post Message(s)]] request's JSON array, thus, the maximum number of messages a client can post one time.  The default value is 20, which means, a request like the following:
 +
 
 +
 +
POST /v1/queues/noein/messages HTTP/1.1
 +
Host: marconi.example.com
 +
 +
...
 +
 +
[
 +
  { "ttl": 300, "body": "msg1" },
 +
  { "ttl": 300, "body": "msg2" },
 +
  ...
 +
 +
  { "ttl": 300, "body": "msg21" }
 +
]
 +
 
 +
will result in a '''400 Bad Request''' response without any message to be posted.
 +
 
 +
* The max integral value of the URI parameter <code>limit</code> in a [[Marconi/specs/api/v1#List Messages]] request URI, thus, the maximum number of messages a client can list one time.  The default value is 20, which means, a request like the following:
 +
 
 +
 
 +
GET /v1/queues/noein/messages?limit=21
 +
 
 +
will result in a '''400 Bad Request''' response.
 +
 
 +
* The max integral value of the URI parameter <code>limit</code> in a [[Marconi/specs/api/v1#Claim Messages]] request URI, thus, the maximum number of messages a client can claim one time.  The default value is 20, which means, a request like the following:
 +
 
 +
 
 +
POST /v1/queues/noein/claims?limit=22
 +
Content-Type: application/json
 +
 +
...
 +
 
 +
will result in a '''400 Bad Request''' response.
 +
 
 +
* The maximum number of message IDs allowed for the URI parameter <code>ids</code> in a [[Marconi/specs/api/v1#Get a Set of Messages by ID]] request URI, thus, the maximum number of messages a client can fetch one time in a bulk getting.  Note that although this is not a paging API, the URI is usually returned in a message posting's "Location" header.  The default value is 20, which means, a request like the following:
 +
 
 +
 
 +
GET /v1/queues/{queue_name}/messages?ids=msg1,msg2,...,msg21
 +
 
 +
will result in a '''400 Bad Request''' response.
 +
 
 +
* The maximum number of message IDs allowed for the URI parameter <code>ids</code> in a [[Marconi/specs/api/v1#Delete a Set of Messages by ID]] request URI, thus, the maximum number of messages a client can delete one time in a bulk deletion.  Note that although this is not a paging API, the URI is usually returned in a message posting's "Location" header.  The default value is 20, which means, a request like the following:
 +
 
 +
 
 +
DELETE /v1/queues/{queue_name}/messages?ids=msg1,msg2,...,msg21
 +
 
 +
will result in a '''400 Bad Request''' response.
 +
 
 +
<tt>message_ttl_max</tt>
 +
 
 +
This variable controls:
 +
 
 +
* The maximum integral value of the <code>ttl</code> fields allowed for each message in a [[Marconi/specs/api/v1#Post Message(s)]] request, thus, the longest time (in seconds) a message can possibly live without being claimed.  Note that the minimum  TTL is 60s.  The default maximum is 1209600s, 14 days.  Which means, a request like the following:
 +
 
 +
 +
POST /v1/queues/noein/messages HTTP/1.1
 +
Host: marconi.example.com
 +
 +
...
 +
 +
[
 +
  { "ttl": 300, "body": "msg1" },
 +
  { "ttl": 1300000, "body": "msg2" },
 +
  ...
 +
 +
  { "ttl": 300, "body": "msg10" }
 +
]
 +
 
 +
will result in a '''400 Bad Request''' response without any message to be posted.
 +
 
 +
<tt>claim_ttl_max</tt>
 +
 
 +
This variable controls the following API limits:
 +
 
 +
* The maximum integral value of the <code>ttl</code> fields allowed in a [[Marconi/specs/api/v1#Claim Messages]] request, thus, the longest time (in seconds) a claim can possibly live.  Note that the minimum TTL is 60s.  The default maximum is 43200s, 12 hours.  A request like the following:
 +
 
 +
 
 +
POST /v1/queues/noein/claims
 +
Content-Type: application/json
 +
...
 +
 +
{ "ttl": 50, "grace": 60 }
 +
 
 +
will result in a '''400 Bad Request''' response.
 +
 
 +
* The maximum integral value of the <code>ttl</code> fields allowed in a [[Marconi/specs/api/v1#Update Claim]] request, thus, the new longest time (in seconds) a claim can possibly have.  Note that the minimum TTL is 60s.  The default maximum is 43200s, 12 hours.  A request like the following:
 +
 
 +
 
 +
PATCH /v1/queues/noein/claims
 +
Content-Type: application/json
 +
...
 +
 +
{ "ttl": 50000 }
 +
 
 +
will result in a '''400 Bad Request''' response.
 +
 
 +
<tt>claim_grace_max</tt>
 +
 
 +
This variable controls:
 +
 
 +
* The maximum integral value of the <code>grace</code> fields allowed in a [[Marconi/specs/api/v1#Claim Messages]] request, thus, the extra time (in seconds) a claim may add to its claimed message.  Note that the minimum grace period is 60s.  The default maximum is 43200s, 12 hours.  A request like the following:
 +
 
 +
 
 +
POST /v1/queues/noein/claims
 +
Content-Type: application/json
 +
...
 +
 +
{ "ttl": 60, "grace": 44000 }
 +
 
 +
will result in a '''400 Bad Request''' response.
 +
 
 +
<tt>metadata_size_uplimit</tt>
 +
 
 +
This variable controls:
 +
 
 +
* The maximum size (in bytes) a JSON dict allowed in a [[Marconi/specs/api/v1#Set Queue Metadata]] request, thus, the max size of a queue metadata.  Note that the Marconi's understanding of "size of JSON" is the size of the compact representation of a JSON (UTF-8 encoded, without extra whitespaces).  The default maximum is 64KiB.  A request like the following:
 +
 
 +
 
 +
PUT /v1/queues/noein/metadata HTTP/1.1
 +
Host: marconi.example.com
 +
...
 +
 +
{
 +
  "key1" : { ... },
 +
  "key2" : ...
 +
}
 +
 
 +
where a JSON in the form of <code>{"key1":{...},"key2":...}</code> is longer than 64KiB, will result in a '''400 Bad Request''' response.
  
 
+
<tt>message_size_uplimit</tt>
  POST /v1/queues/noein/messages HTTP/1.1
 
  Host: marconi.example.com
 
 
 
  ...
 
 
 
  [
 
    { "ttl": 300, "body": "msg1" },
 
    { "ttl": 300, "body": "msg2" },
 
    ...
 
 
 
    { "ttl": 300, "body": "msg21" }
 
  ]
 
  
will result in '''400 Bad Request''' response.
+
This variable controls:
  
* The max integral value of the URI parameter "limit" in a [[Marconi/specs/api/v1#List_Messages]] request URI, thus the maxinum number of messages a client can expect in the "messages" section of the response's JSON object.  The default value is 20, which means, a request like the following:
+
* The maximum size (in bytes) of the value allowed in each <code>body</code> field in a [[Marconi/specs/api/v1#Post Message(s)]] request, thus, the max size of a message content.  Note that the Marconi's understanding of "size of JSON" is the size of the compact representation of a JSON (UTF-8 encoded, without extra whitespaces).  The default maximum is 256KiB.  A request like the following:
  
  
  GET /v1/queues/noein/messages?limit=21
+
POST /v1/queues/noein/messages HTTP/1.1
 +
Host: marconi.example.com
 +
...
 +
 +
[
 +
  { "ttl": 60, "body": "msg1" },
 +
  { "ttl": 60, "body": [...] },
 +
  ...
 +
 +
  { "ttl": 60, "body": "msg10" }
 +
]
  
will result in '''400 Bad Request''' response.
+
where the second entry has a JSON value of the <code>body</code> key, and the JSON is longer than 256KiB, will result in a '''400 Bad Request''' response without any message to be posted.

Latest revision as of 18:42, 7 August 2014

Marconi API Limits

Config Options & Default Values:

The following limits can be changed in marconi.conf, under the [limits:transport] section.

  • queue_paging_uplimit – 20
  • message_paging_uplimit – 20
  • message_ttl_max – 1209600 (seconds, 14 days)
  • claim_ttl_max – 43200 (seconds, 12 hours)
  • claim_grace_max – 43200 (seconds, 12 hours)
  • metadata_size_uplimit – 65536 (bytes, 64 KiB)
  • message_size_uplimit – 262144 (bytes, 256 KiB)
Description

queue_paging_uplimit

This variable controls:

  • The max integral value of the URI parameter limit a client can use in a Marconi/specs/api/v1#List Queues request URI, thus, the maximum number of queues a client can list one time. The default value is 20, which means, a request like the following:


GET /v1/queues?limit=30

will result in a 400 Bad Request response.

message_paging_uplimit

This variable controls the following API limits:

  • The maximum items a client can put in a Marconi/specs/api/v1#Post Message(s) request's JSON array, thus, the maximum number of messages a client can post one time. The default value is 20, which means, a request like the following:


POST /v1/queues/noein/messages HTTP/1.1
Host: marconi.example.com

...

[
  { "ttl": 300, "body": "msg1" },
  { "ttl": 300, "body": "msg2" },
  ...

  { "ttl": 300, "body": "msg21" }
]

will result in a 400 Bad Request response without any message to be posted.

  • The max integral value of the URI parameter limit in a Marconi/specs/api/v1#List Messages request URI, thus, the maximum number of messages a client can list one time. The default value is 20, which means, a request like the following:


GET /v1/queues/noein/messages?limit=21

will result in a 400 Bad Request response.

  • The max integral value of the URI parameter limit in a Marconi/specs/api/v1#Claim Messages request URI, thus, the maximum number of messages a client can claim one time. The default value is 20, which means, a request like the following:


POST /v1/queues/noein/claims?limit=22
Content-Type: application/json

...

will result in a 400 Bad Request response.

  • The maximum number of message IDs allowed for the URI parameter ids in a Marconi/specs/api/v1#Get a Set of Messages by ID request URI, thus, the maximum number of messages a client can fetch one time in a bulk getting. Note that although this is not a paging API, the URI is usually returned in a message posting's "Location" header. The default value is 20, which means, a request like the following:


GET /v1/queues/{queue_name}/messages?ids=msg1,msg2,...,msg21

will result in a 400 Bad Request response.

  • The maximum number of message IDs allowed for the URI parameter ids in a Marconi/specs/api/v1#Delete a Set of Messages by ID request URI, thus, the maximum number of messages a client can delete one time in a bulk deletion. Note that although this is not a paging API, the URI is usually returned in a message posting's "Location" header. The default value is 20, which means, a request like the following:


DELETE /v1/queues/{queue_name}/messages?ids=msg1,msg2,...,msg21

will result in a 400 Bad Request response.

message_ttl_max

This variable controls:

  • The maximum integral value of the ttl fields allowed for each message in a Marconi/specs/api/v1#Post Message(s) request, thus, the longest time (in seconds) a message can possibly live without being claimed. Note that the minimum TTL is 60s. The default maximum is 1209600s, 14 days. Which means, a request like the following:


POST /v1/queues/noein/messages HTTP/1.1
Host: marconi.example.com

...

[
  { "ttl": 300, "body": "msg1" },
  { "ttl": 1300000, "body": "msg2" },
  ...

  { "ttl": 300, "body": "msg10" }
]

will result in a 400 Bad Request response without any message to be posted.

claim_ttl_max

This variable controls the following API limits:

  • The maximum integral value of the ttl fields allowed in a Marconi/specs/api/v1#Claim Messages request, thus, the longest time (in seconds) a claim can possibly live. Note that the minimum TTL is 60s. The default maximum is 43200s, 12 hours. A request like the following:


POST /v1/queues/noein/claims
Content-Type: application/json
...

{ "ttl": 50, "grace": 60 }

will result in a 400 Bad Request response.

  • The maximum integral value of the ttl fields allowed in a Marconi/specs/api/v1#Update Claim request, thus, the new longest time (in seconds) a claim can possibly have. Note that the minimum TTL is 60s. The default maximum is 43200s, 12 hours. A request like the following:


PATCH /v1/queues/noein/claims
Content-Type: application/json
...

{ "ttl": 50000 }

will result in a 400 Bad Request response.

claim_grace_max

This variable controls:

  • The maximum integral value of the grace fields allowed in a Marconi/specs/api/v1#Claim Messages request, thus, the extra time (in seconds) a claim may add to its claimed message. Note that the minimum grace period is 60s. The default maximum is 43200s, 12 hours. A request like the following:


POST /v1/queues/noein/claims
Content-Type: application/json
...

{ "ttl": 60, "grace": 44000 }

will result in a 400 Bad Request response.

metadata_size_uplimit

This variable controls:

  • The maximum size (in bytes) a JSON dict allowed in a Marconi/specs/api/v1#Set Queue Metadata request, thus, the max size of a queue metadata. Note that the Marconi's understanding of "size of JSON" is the size of the compact representation of a JSON (UTF-8 encoded, without extra whitespaces). The default maximum is 64KiB. A request like the following:


PUT /v1/queues/noein/metadata HTTP/1.1
Host: marconi.example.com
...

{
  "key1" : { ... },
  "key2" : ...
}

where a JSON in the form of {"key1":{...},"key2":...} is longer than 64KiB, will result in a 400 Bad Request response.

message_size_uplimit

This variable controls:

  • The maximum size (in bytes) of the value allowed in each body field in a Marconi/specs/api/v1#Post Message(s) request, thus, the max size of a message content. Note that the Marconi's understanding of "size of JSON" is the size of the compact representation of a JSON (UTF-8 encoded, without extra whitespaces). The default maximum is 256KiB. A request like the following:


POST /v1/queues/noein/messages HTTP/1.1
Host: marconi.example.com
...

[
  { "ttl": 60, "body": "msg1" },
  { "ttl": 60, "body": [...] },
  ...

  { "ttl": 60, "body": "msg10" }
]

where the second entry has a JSON value of the body key, and the JSON is longer than 256KiB, will result in a 400 Bad Request response without any message to be posted.