Difference between revisions of "MagnetoDB/specs/data-api"
Ikhudoshyn (talk | contribs) (→Headers) |
Achudnovets (talk | contribs) (→Request Parameters) |
||
Line 147: | Line 147: | ||
===== Request Parameters ===== | ===== Request Parameters ===== | ||
+ | |||
+ | ;table_name | ||
+ | : The name of the table. Unique per project. | ||
+ | : Type: string | ||
+ | : Required: Yes | ||
;attribute_definitions | ;attribute_definitions |
Revision as of 17:27, 18 March 2014
Contents
- 1 [Draft] MagnetoDB API
- 1.1 Headers
- 1.2 Common Errors
- 1.3 Managing Tables
- 1.4 Managing items
- 1.5 Batch methods
- 1.6 Operation details
[Draft] MagnetoDB API
Headers
- User-Agent
- Content-Type:application/json
- Accept
- X-Auth-Token keystone auth token
Common Errors
This section lists the common errors that all actions return. Any action-specific errors will be listed in the topic for the action.
- InternalFailure
- Unknown error, exception or failure.
- HTTP Status Code: 500
- RequestQuotaExceeded
- Server is overloaded or caller has exceeded request quota.
- HTTP Status Code: 429
- OverLimit
- Caller is exceeded data storage quota.
- HTTP Status Code: 413
- InvalidClientToken
- The Keystone token does not exist or expired.
- HTTP Status Code: 401
- Forbidden
- Caller is not authorized for operation.
- HTTP Status Code: 403
- InvalidParameterCombination
- Parameters that must not be used together were used together.
- HTTP Status Code: 400
- InvalidParameterValue
- An invalid or out-of-range value was supplied for the input parameter.
- HTTP Status Code: 400
- InvalidQueryParameter
- The query string is malformed or does not adhere to standards.
- HTTP Status Code: 400
- MalformedQueryString
- The query string contains a syntax error.
- HTTP Status Code: 404
- MissingParameter
- A required parameter for the specified action is not supplied.
- HTTP Status Code: 400
- ServiceUnavailable
- Temporary failure of the server.
- HTTP Status Code: 503
- ValidationError
- Value validation failed.
- HTTP Status Code: 400
Managing Tables
HTTP method | URL pattern | Operation description | Amazon DynamoDB operation |
---|---|---|---|
POST | v1/{project_id}/data/tables | Creates a table | CreateTable |
PUT | v1/{project_id}/data/tables/{table_name} | Modifies settings for a table | UpdateTable |
DELETE | v1/{project_id}/data/tables/{table_name} | Deletes a table and all of its indexes | DeleteTable |
GET | v1/{project_id}/data/tables | Lists tables | ListTables |
GET | v1/{project_id}/data/tables/{table_name} | Describes table | DescribeTable |
Managing items
HTTP method | URL pattern | Operation description | Amazon DynamoDB operation |
---|---|---|---|
POST | v1/{project_id}/data/tables/{table_name}/put_item | Creates an item in the table | Putitem |
POST | v1/{project_id}/data/tables/{table_name}/put_item | Updates an item in the table | Updateitem |
POST | v1/{project_id}/data/tables/{table_name}/delete_item | Deletes an item from the table | Deleteitem |
POST | v1/{project_id}/data/tables/{table_name}/get_item | Gets an item from the table | Getitem |
POST | v1/{project_id}/data/tables/{table_name}/query | Directly accesses items from a tableusing the table primary key, or from an index using the index key | Query |
POST | v1/{project_id}/data/tables/{table_name}/scan | Returns one or more items and item attributes by accessing every item in the table | Scan |
Batch methods
HTTP method | URL pattern | Operation description | Amazon DynamoDB operation |
---|---|---|---|
POST | v1/{project_id}/data/batch_get_item | Returns the attributes of one or more items from one or more tables. You identify requested items by primary key | BatchGetitem |
POST | v1/{project_id}/data/batch_write_item | Puts or deletes multiple items in one or more tables | BatchWriteitem |
Operation details
Requests and responses should be very similar to the Amazon DynamoDB. But there should be some differences:
- table_name parameter will be provided via URL
- GlobalSecondaryIndexes will be added in future
- API will use different HTTP methods for different operations (POST for create, PUT for update, etc)
Note: operations with items in the table(Getitem, Putitem, Scan, etc) will use POST method.
CreateTable
The CreateTable operation adds a new table. Table names must be unique within each tenant.
URL
POST v1/{project_id}/data/tables
Request Syntax
{ "attribute_definitions": [ { "attribute_name": "string", "attribute_type": "string" } ], "key_schema": [ { "attribute_name": "string", "key_type": "string" } ], "local_secondary_indexes": [ { "index_name": "string", "key_schema": [ { "attribute_name": "string", "key_type": "string" } ], "projection": { "non_key_attributes": [ "string" ], "projection_type": "string" } } ], "table_name": "string" }
Request Parameters
- table_name
- The name of the table. Unique per project.
- Type: string
- Required: Yes
- attribute_definitions
- An array of attributes that describe the key schema for the table and indexes.
- Type: array of AttributeDefinition objects
- Required: Yes
- key_schema
- Specifies the attributes that make up the primary key for a table or an index.
- Type: array of key_schemaElement objects
- Required: Yes
- local_secondary_indexes
- One or more local secondary indexes to be created on the table.
- Type: array of objects
- Required: No
Response Syntax
{ "table_description": { "attribute_definitions": [ { "attribute_name": "string", "attribute_type": "string" } ], "creation_datetime": "number", "item_count": "number", "key_schema": [ { "attribute_name": "string", "key_type": "string" } ], "local_secondary_indexes": [ { "index_name": "string", "index_size_bytes": "number", "item_count": "number", "key_schema": [ { "attribute_name": "string", "key_type": "string" } ], "projection": { "non_key_attributes": [ "string" ], "projection_type": "string" } } ], "links": [ { "href": "url", "rel": "self" }, { "href": "url", "rel": "bookmark" } ], "table_size_bytes": "number", "table_status": "string" } }
Response Elements
- table_description
- Represents the properties of a table.
- Type: table_description object
Errors
TBW
UpdateTable
In the MagnetoDB this operation updates provisioned throughput. We can use this operation for updating OpenStack staff and GlobalSecondaryIndexes.
URL
PUT v1/{project_id}/data/tables/{table_name}
Request Syntax
TODO
Request Parameters
TODO
Response Syntax
TODO
Response Elements
TODO
Errors
TODO
DescribeTable
Returns information about the table.
URL
GET v1/{project_id}/data/tables/{table_name}
Request Syntax
This operation does not require a request body
Response Syntax
{ "table": { "attribute_definitions": [ { "attribute_name": "string", "attribute_type": "string" } ], "creation_datetime": "number", "item_count": "number", "key_schema": [ { "attribute_name": "string", "key_type": "string" } ], "local_secondary_indexes": [ { "index_name": "string", "index_size_bytes": "number", "item_count": "number", "key_schema": [ { "attribute_name": "string", "key_type": "string" } ], "projection": { "non_key_attributes": [ "string" ], "projection_type": "string" } } ], "links": [ { "href": "url", "rel": "self" } ], "table_name": "string", "table_size_bytes": "number", "table_status": "string" } }
Response Elements
- table
- Represents the properties of a table.
- Type: table_description object
Errors
TBW
DeleteTable
The DeleteTable operation deletes a table and all of its items.
URL
DELETE v1/{project_id}/data/tables/{table_name}
Request Syntax
This operation does not require a request body
Response Syntax
{ "table_description": { "attribute_definitions": [ { "attribute_name": "string", "attribute_type": "string" } ], "creation_datetime": "number", "item_count": "number", "key_schema": [ { "attribute_name": "string", "key_type": "string" } ], "local_secondary_indexes": [ { "index_name": "string", "index_size_bytes": "number", "item_count": "number", "key_schema": [ { "attribute_name": "string", "key_type": "string" } ], "projection": { "non_key_attributes": [ "string" ], "projection_type": "string" } } ], "links": [ { "href": "url", "rel": "self" } ], "table_size_bytes": "number", "table_status": "string" } }
Response Elements
- table_description
- Represents the properties of a table.
- Type: table_description object
Errors
TBW
ListTables
Returns an array of table describing info associated with the current user in given tenant.
URL
GET v1/{project_id}/data/tables
Request Syntax
This operation does not require a request body
Request Parameters
Parameters should be provided via GET query string.
- start_table_name
- The first table name that this operation will evaluate.
- Type: xsd:string
- Required: No
- limit
- A maximum number of the items to return.
- Type: xsd:int
- Required: No
Response Syntax
{ "last_evaluated_table_name": "string", "tables": [ { "rel": "string", "href": "url" } ] }
Response Elements
- last_evaluated_table_name
- The name of the last table in the current page of results.
- Type: String
- tables
- Array of the table info items
- Type: array of structs
Errors
TBW
Putitem
Creates a new item, or replaces an old item.
URL
POST v1/{project_id}/data/tables/{table_name}/put_item
Request Syntax
{ "expected": { "string" : { "exists": "boolean", "value": { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } } }, "item": { "string" : { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } }, "time_to_live":"number", "return_values": "string" }
Request Parameters
- item
- A map of attribute name/value pairs, one for each attribute. Only the primary key attributes are required.
- Type: String to Attributevalue object map
- Required: Yes
- expected
- The conditional block for the Putitem operation.
- Type: String to expectedAttributevalue object map
- Required: No
- time_to_live
- Defines time to live for item
- Type: number
- Valid values: 0 - MAX_NUMBER
- Required: No
- return_values
- Use return_values if you want to get the item attributes as they appeared before they were updated.
- Type: String
- Valid values: NONE | ALL_OLD | UPDATED_OLD | ALL_NEW | UPDATED_NEW
- Required: No
Response Syntax
{ "attributes": { "string" : { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } } }
Response Elements
- attributes
- The attribute values as they appeared before the PutiItem operation.
- Type: String to attribute struct
Errors
TBW
Getitem
The Getitem operation returns an item with the given primary key.
URL
POST v1/{project_id}/data/tables/{table_name}/get_item
Request Syntax
{ "attributes_to_get": [ "string" ], "consistent_read": "boolean", "key": { "string" : { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } } }
Request Parameters
- key
- The primary key of the item to retrieve.
- Type: String to object map
- Required: Yes
- attributes_to_get
- The names of one or more attributes to retrieve.
- Type: array of Strings
- Required: No
- consistent_read
- Use or not use strongly consistent read.
- Type: Boolean
- Required: No
Response Syntax
{ "item": { "string" : { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } } }
Response Elements
- item
- An itemi with attributes.
- Type: String to object map
Errors
TBW
Updateitem
Edits(or inserts if item does not already exist) an item's attributes.
URL
POST v1/{project_id}/data/tables/{table_name}/update_item
Request Syntax
{ "attribute_updates": { "string" : { "action": "string", "value": { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } } }, "time_to_live":"number", "expected": { "string" : { "exists": "boolean", "value": { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } } }, "key": { "string" : { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } }, "return_values": "string" }
Request Parameters
- key
- The primary key.
- Type: String to object map
- Required: Yes
- attribute_updates
- The names of attributes to be modified, the action to perform on each, and the new value for each.
- Type: String to object map
- Required: No
- time_to_live
- Defines time to live for item
- Type: number
- Valid values: 0 - MAX_NUMBER
- Required: No
- expected
- The conditional block for the Updateitem operation. All the conditions must be met for the operation to succeed.
- Type: String to object map
- Required: No
- return_values
- Type: String
- Valid values: NONE | ALL_OLD | UPDATED_OLD | ALL_NEW | UPDATED_NEW
- Required: No
Response Syntax
{ "attributes": { "string" : { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } } }
Response Elements
- attributes
- Item attributes
- Type: String to object map
Errors
TBW
Deleteitem
Deletes a single item in a table by primary key.
URL
POST v1/{project_id}/data/tables/{table_name}/delete_item
Request Syntax
{ "expected": { "string" : { "exists": "boolean", "value": { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } } }, "key": { "string" : { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } }, "return_values": "string" }
Request Parameters
- key
- Primary key of the item to delete.
- Type: String to object map
- Required: Yes
- expected
- The conditional block for the DeleteItem operation. All the conditions must be met for the operation to succeed.
- Type: String to object map
- Required: No
- return_values
- Type: String
- Valid values: NONE | ALL_OLD | UPDATED_OLD | ALL_NEW | UPDATED_NEW
- Required: No
Response Syntax
{ "attributes": { "string" : { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } } }
Response Elements
- attributes
- Item attributes
- Type: String to Attributevalue object map
Errors
TBW
Query
Query for an items py primary or index key.
URL
POST v1/{project_id}/data/tables/{table_name}/query
Request Syntax
{ "attributes_to_get": [ "string" ], "consistent_read": "boolean", "exclusive_start_key": { "string" : { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } }, "index_name": "string", "key_conditions": { "string" : { "attribute_value_list": [ { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } ], "comparison_operator": "string" } }, "limit": "number", "scan_index_forward": "boolean", "select": "string" }
Request Parameters
- attributes_to_get
- Type: array of Strings
- Required: No
- consistent_read
- Type: Boolean
- Required: No
- exclusive_start_key
- The primary key of the first item that this operation will evaluate.
- Type: String to object map
- Required: No
- index_name
- The name of an index to query.
- Type: String
- Required: No
- key_conditions
- The selection criteria for the query.
- Type: String to Condition object map
- Required: No
- limit
- Type: Number
- Required: No
- scan_index_forward
- Type: Boolean
- Required: No
- select
- The attributes to be returned in the result.
- Type: String
- Valid values: ALL_ATTRIBUTES | ALL_PROJECTED_ATTRIBUTES | SPECIFIC_ATTRIBUTES | COUNT
- Required: No
Response Syntax
{ "count": "number", "items": [ { "string" : { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } } ], "last_evaluated_key": { "string" : { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } } }
Response Elements
- count
- Type: Number
- items
- An array of items.
- Type: array of items
- last_evaluated_key
- The primary key of the item where the operation stopped.
- Type: String to object map
Errors
TBW
Scan
The Scan operation returns one or more items and item attributes by accessing every item in the table.
URL
POST v1/{project_id}/data/tables/{table_name}/scan
Request Syntax
{ "attributes_to_get": [ "string" ], "exclusive_start_key": { "string" : { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } }, "limit": "number", "scan_filter": { "string" : { "attribute_value_list": [ { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } ], "comparison_operator": "string" } }, "segment": "number", "select": "string", "total_segments": "number" } ===== Request Parameters ===== ;attributes_to_get : Type: array of Strings : Required: No ;exclusive_start_key : Type: String to Attributevalue object map : Required: No ;limit : Type: Number : Required: No ;scan_filter : Scan conditions. : Type: String to Condition object map : Required: No ;segment : Segment for parallel scan. : Type: Number : Required: No ;select : Attributes to select. : Type: String : Valid values: ALL_ATTRIBUTES | ALL_PROJECTED_ATTRIBUTES | SPECIFIC_ATTRIBUTES | COUNT : Required: No ;total_segments : Number of segments for parallel scan. : Type: Number : Required: No ===== Response Syntax ===== <pre> { "count": "number", "items": [ { "string" : { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } } ], "last_evaluated_key": { "string" : { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } }, "scanned_count": "number" }
Response Elements
- count
- The number of items in the response.
- Type: Number
- items
- An array of items.
- Type: array of items
- last_evaluated_key
- Type: String to Attributevalue object map
- scanned_count
- Type: Number
Errors
TBW
BatchGetItem
The BatchGetitem operation returns the attributes of one or more items from one or more tables.
URL
POST v1/{project_id}/data/batch_get_item
Request Syntax
{ "request_items": { "string" : { "attributes_to_get": [ "string" ], "consistent_read": "boolean", "keys": [ { "string" : { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } } ] } } }
Request Parameters
- request_items
- Type: String to object map
- Required: Yes
Response Syntax
{ "responses": { "string" : [ { "string" : { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } } ] }, "unprocessed_keys": { "string" : { "attributes_to_get": [ "string" ], "consistent_read": "boolean", "keys": [ { "string" : { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } } ] } } }
Response Elements
- responses
- Type: String to map
- unprocessed_keys
- Type: String to object map
Errors
TBW
BatchWriteItem
The BatchWriteItem operation puts or deletes multiple items in one or more tables.
URL
POST v1/{project_id}/data/batch_write_item
Request Syntax
{ "request_items": { "string" : [ { "delete_request": { "key": { "string" : { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } } }, "put_request": { "item": { "string" : { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } }, "time_to_live":"number" } } ] } }
Request Parameters
- request_items
- Type: String to object map
- Required: Yes
Response Syntax
{ "unprocessed_items": { "string" : [ { "delete_request": { "key": { "string" : { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } } }, "put_request": { "item": { "string" : { "B": "blob", "BS": [ "blob" ], "N": "string", "NS": [ "string" ], "S": "string", "SS": [ "string" ] } }, "time_to_live":"number" } } ] } }
Response Elements
- unprocessed_items
- Type: String to object map
Errors
TBW