Jump to: navigation, search

MagnetoDB/specs/data-api

< MagnetoDB
Revision as of 12:05, 28 March 2014 by Oleksandr Minakov (talk | contribs) (Request Parameters)

Contents

[Draft] MagnetoDB API

Headers

  • User-Agent
  • Content-Type: application/json
  • Accept: application/json
  • 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
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