Sahara/ApiProposal
< Sahara
Revision as of 13:37, 16 April 2013 by David Dobbins (talk | contribs)
Contents
- 1 Proposal Only
- 2 List of API Calls
- 3 Common Error Responses
- 4 API Call Details
Proposal Only
Please recognize that this is only a proposed DSL to be considered for development. This specification is NOT YET IMPLEMENTED.
List of API Calls
| Verb | URI | Description | Representations |
|---|---|---|---|
| POST | /clusters | Create a cluster | JSON, XML |
| DELETE | /clusters/{clusterId} | Delete a cluster | JSON, XML |
| GET | /clusters | List all the clusters for the user | JSON, XML |
| GET | /clusters/{clusterId} | Get details about a cluster | JSON, XML |
| POST | /clusters/{clusterId}/action | Perform actions on a cluster (e.g. resize) | JSON, XML |
| GET | /clusters/{clusterId}/nodes | List all nodes in a cluster | JSON, XML |
| GET | /clusters/{clusterId}/nodes/{nodeId} | Get details about a node in a cluster | JSON, XML |
| GET | /profile | Get information about the current user profile | JSON, XML |
| POST | /profile | Update an existing profile | JSON, XML |
| GET | /limits | List all the resource limits for the user | JSON, XML |
| GET | /flavors | List all available flavors | JSON, XML |
| GET | /flavors/{flavorId} | Get details about a flavor | JSON, XML |
| GET | /flavors/{flavorid}/types | List the supported cluster types for a flavor | JSON, XML |
| GET | /types | List all available cluster types | JSON, XML |
| GET | /types/{typeId} | Get details about a cluster type | JSON, XML |
| GET | /types/{typeid}/flavors | List the supported flavors for a cluster type | JSON, XML |
Common Error Responses
| Response Code | Element | Message |
|---|---|---|
| 401 | unauthorized | Not authorized. |
| 403 | forbidden | Access is denied to this resource. |
| 404 | itemNotFound | The resource could not be found. |
| 500 | fault (Not implemented yet) | An unknown exception occurred. |
API Call Details
Clusters
Create a cluster
| Verb | URI | Description | Representations |
|---|---|---|---|
| POST | /clusters | Create a cluster | JSON, XML |
Request
{
"cluster": {
"name": "slice",
"clusterType": "hadoop",
"flavorId": "2",
"nodeCount": 5
}
}
Response
{
"cluster": {
"id": "db478fc1-2d86-4597-8010-cbe787bbbc41",
"created": "2012-12-27T10:10:10Z",
"updated": "",
"name": "slice",
"clusterType": "hadoop",
"flavorId": "2",
"nodeCount": 5,
"status": "BUILD",
"links": [
{
"rel": "self",
"href": "https://bigdata.api.rackspacecloud.com/v1.0/1234/clusters/db478fc1-2d86-4597-8010-cbe787bbbc41"
},
{
"rel": "bookmark",
"href": "https://bigdata.api.rackspacecloud.com/1234/clusters/db478fc1-2d86-4597-8010-cbe787bbbc41"
}
]
}
}
| Response Code | Message |
|---|---|
| 200 | Success |
| 400 | Invalid Response Body |
| 400 | User profile needs to be created |
| 400 | Invalid Node Count |
| 400 | Not valid flavor |
| 400 | Malformed Data |
| 413 | Over Limits (Quota Exceeded) |
Delete a cluster
| Verb | URI | Description | Representations |
|---|---|---|---|
| DELETE | /clusters/{clusterid} | Delete a cluster | JSON, XML |
Request
N/A
Response
{
"cluster": {
"id": "db478fc1-2d86-4597-8010-cbe787bbbc41",
"created": "2012-12-27T10:10:10Z",
"updated": "",
"name": "slice",
"clusterType": "hadoop",
"flavorId": "2",
"nodeCount": 5,
"status": "DELETING",
"links": [
{
"rel": "self",
"href": "https://bigdata.api.rackspacecloud.com/v1.0/1234/clusters/db478fc1-2d86-4597-8010-cbe787bbbc41"
},
{
"rel": "bookmark",
"href": "https://bigdata.api.rackspacecloud.com/1234/clusters/db478fc1-2d86-4597-8010-cbe787bbbc41"
}
]
}
}
| Response Code | Message |
|---|---|
| 202 | Accepted |
| 400 | Cannot delete |
| 404 | Resource not found |
| 409 | Invalid state |
List clusters
Verb URI Description Representations GET /clusters List all the clusters for the user JSON, XML
Request
N/A
Response
{
"clusters": [
{
"id": "db478fc1-2d86-4597-8010-cbe787bbbc41",
"name": "slice",
"created": "2012-12-27T10:10:10Z",
"updated": "2012-12-27T10:15:10Z",
"clusterType": "hadoop",
"flavorId": "2",
"nodeCount": 5,
"status": "ACTIVE",
"links": [
{
"rel": "self",
"href": "https://bigdata.api.rackspacecloud.com/v1.0/1234/clusters/db478fc1-2d86-4597-8010-cbe787bbbc41"
},
{
"rel": "bookmark",
"href": "https://bigdata.api.rackspacecloud.com/1234/clusters/db478fc1-2d86-4597-8010-cbe787bbbc41"
}
]
},
{
"id": "ac111111-2d86-4597-8010-cbe787bbbc41",
"name": "real",
"created": "2012-12-27T10:10:10Z",
"updated": "2012-12-27T10:15:10Z",
"clusterType": "hbase",
"flavorId": "4",
"nodeCount": 20,
"status": "ACTIVE",
"links": [
{
"rel": "self",
"href": "https://bigdata.api.rackspacecloud.com/v1.0/1234/clusters/ac111111-2d86-4597-8010-cbe787bbbc41"
},
{
"rel": "bookmark",
"href": "https://bigdata.api.rackspacecloud.com/1234/clusters/ac111111-2d86-4597-8010-cbe787bbbc41"
}
]
}
]
}
Response Code Message
200 Success
Get cluster details
Verb URI Description Representations GET /clusters/{clusterId} Get details about a cluster JSON, XML
Request
N/A
Response
{
"cluster": {
"id": "db478fc1-2d86-4597-8010-cbe787bbbc41",
"created": "2012-12-27T10:10:10Z",
"updated": "2012-12-27T10:20:10Z",
"name": "slice",
"clusterType": "hadoop",
"flavorId": "2",
"nodeCount": 5,
"status": "ACTIVE",
"links": [
{
"rel": "self",
"href": "https://bigdata.api.rackspacecloud.com/v1.0/1234/clusters/db478fc1-2d86-4597-8010-cbe787bbbc41"
},
{
"rel": "bookmark",
"href": "https://bigdata.api.rackspacecloud.com/1234/clusters/db478fc1-2d86-4597-8010-cbe787bbbc41"
}
]
}
}
Response Code Message 200 Success 404 Resource not found
Perform actions on a cluster
Verb URI Description Representations POST /clusters/{clusterId}/action Perform actions on a cluster (e.g. resize) JSON, XML
Request
{
"resize": {
"nodeCount": 10
}
}
Response
{
"cluster": {
"id": "db478fc1-2d86-4597-8010-cbe787bbbc41",
"created": "2012-12-27T10:10:10Z",
"updated": "2012-12-27T16:20:10Z",
"name": "slice",
"clusterType": "hadoop",
"flavorId": "2",
"nodeCount": 10,
"status": "RESIZING",
"links": [
{
"rel": "self",
"href": "https://bigdata.api.rackspacecloud.com/v1.0/1234/clusters/db478fc1-2d86-4597-8010-cbe787bbbc41"
},
{
"rel": "bookmark",
"href": "https://bigdata.api.rackspacecloud.com/1234/clusters/db478fc1-2d86-4597-8010-cbe787bbbc41"
}
]
}
}
Response Code Message 200 Success 400 Unacceptable parameters 400 Malformed data 404 The resource cannot be found 409 Invalid state
Nodes
List nodes in a cluster
Verb URI Description Representations GET /clusters/{clusterId}/nodes List all nodes in a cluster JSON, XML
Request
N/A
Response
{
"nodes": [
{
"id": "000",
"created": "2012-12-27T10:10:10Z",
"role": "NAMENODE",
"name": "NAMENODE-1",
"status": "ACTIVE",
"addresses": {
"public": [
{
"addr": "168.x.x.3",
"version": 4
}
],
"private": [
{
"addr": "10.x.x.3",
"version": 4
}
]
},
"services": {
"namenode": {},
"jobtracker": {},
"ssh": {
"uri": "ssh://user@168.x.x.3"
}
},
"links": [
{
"rel": "self",
"href": "https://bigdata.api.rackspacecloud.com/v1.0/1234/clusters/db478fc1-2d86-4597-8010-cbe787bbbc41/nodes/000"
},
{
"rel": "bookmark",
"href": "https://bigdata.api.rackspacecloud.com/1234/clusters/db478fc1-2d86-4597-8010-cbe787bbbc41/nodes/000"
}
]
},
{
"id": "aaa",
"role": "GATEWAY",
"name": "GATEWAY-1",
"status": "ACTIVE",
"addresses": {
"public": [
{
"addr": "168.x.x.4",
"version": 4
}
],
"private": [
{
"addr": "10.x.x.4",
"version": 4
}
]
},
"services": {
"pig": {},
"hive": {},
"ssh": {
"uri": "ssh://user@168.x.x.4"
},
"status": {
"uri": "http://10.x.x.4"
},
"hdfs-scp": {
"uri": "scp://user@168.x.x.4:9022"
}
},
"links": [
{
"rel": "self",
"href": "https://bigdata.api.rackspacecloud.com/v1.0/1234/clusters/db478fc1-2d86-4597-8010-cbe787bbbc41/nodes/aaa"
},
{
"rel": "bookmark",
"href": "https://bigdata.api.rackspacecloud.com/1234/clusters/db478fc1-2d86-4597-8010-cbe787bbbc41/nodes/aaa"
}
]
},
{
"id": "bbb",
"role": "DATANODE",
"name": "DATANODE-1",
"status": "ACTIVE",
"addresses": {
"public": [
{
"addr": "168.x.x.5",
"version": 4
}
],
"private": [
{
"addr": "10.x.x.5",
"version": 4
}
]
},
"services": {
"datanode": {},
"tasktracker": {},
"ssh": {
"uri": "ssh://user@168.x.x.5"
}
},
"links": [
{
"rel": "self",
"href": "https://bigdata.api.rackspacecloud.com/v1.0/1234/clusters/db478fc1-2d86-4597-8010-cbe787bbbc41/nodes/bbb"
},
{
"rel": "bookmark",
"href": "https://bigdata.api.rackspacecloud.com/1234/clusters/db478fc1-2d86-4597-8010-cbe787bbbc41/nodes/bbb"
}
]
},
{
"id": "ccc",
"role": "DATANODE",
"name": "DATANODE-2",
"status": "ACTIVE",
"addresses": {
"public": [
{
"addr": "168.x.x.6",
"version": 4
}
],
"private": [
{
"addr": "10.x.x.6",
"version": 4
}
]
},
"services": {
"datanode": {},
"tasktracker": {},
"ssh": {
"uri": "ssh://user@168.x.x.6"
}
},
"links": [
{
"rel": "self",
"href": "https://bigdata.api.rackspacecloud.com/v1.0/1234/clusters/db478fc1-2d86-4597-8010-cbe787bbbc41/nodes/ccc"
},
{
"rel": "bookmark",
"href": "https://bigdata.api.rackspacecloud.com/1234/clusters/db478fc1-2d86-4597-8010-cbe787bbbc41/nodes/ccc"
}
]
}
]
}
Response Code Message 200 Success 404 The resource cannot be found
Get details about a node
Verb URI Description Representations GET /clusters/{clusterId}/nodes/{nodeId} Get details about a node in a cluster JSON, XML
Request
N/A
Response
{
"node": {
"id": "000",
"created": "2012-12-27T10:10:10Z",
"role": "NAMENODE",
"name": "NAMENODE-1",
"status": "ACTIVE",
"addresses": {
"public": [
{
"addr": "168.x.x.3",
"version": 4
}
],
"private": [
{
"addr": "10.x.x.3",
"version": 4
}
]
},
"services": {
"namenode": {},
"jobtracker": {},
"ssh": {
"uri": "ssh://user@168.x.x.3"
}
},
"links": [
{
"rel": "self",
"href": "https://bigdata.api.rackspacecloud.com/v1.0/1234/clusters/db478fc1-2d86-4597-8010-cbe787bbbc41/nodes/000"
},
{
"rel": "bookmark",
"href": "https://bigdata.api.rackspacecloud.com/1234/clusters/db478fc1-2d86-4597-8010-cbe787bbbc41/nodes/000"
}
]
}
}
Response Code Message 200 Success 404 The resource cannot be found
Profile
Get information about the current user profile
Verb URI Description Representations GET /profile Get information about the current user profile JSON, XML
Request
N/A
Response
{
"profile": {
"username": "john.doe",
"user_id": "12346",
"tenant_id": "123456",
"sshkeys": [
{
"name": "t@test"
}
],
"cloudCredentials": {},
"links": [
{
"rel": "self",
"href": "https://bigdata.api.rackspacecloud.com/v1.0/123456/profile"
},
{
"rel": "bookmark",
"href": "https://bigdata.api.rackspacecloud.com/123456/profile"
}
]
}
}
Response Code Message 200 Success
Update an existing profile
Verb URI Description Representations POST /profile Update an existing profile JSON, XML
Request
{
"profile": {
"username": "john.doe",
"password": "j0Hnd03",
"sshkeys": [
{
"name": "t@test",
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCtUFnkFrqDDCgEqW1akQkpMOX Owwvg73PLn5Z5QgvxjvJhRCg9ZTR/OWXpWcYqFVNagH4Zs8NOb9921TyQ+ydMnatOM haxMh1ZwTgaUcvndOF8fY+kcERiw1l0iT95w42F8IdUH42Z+8KihZM8gVsbMS6qYTi OM29WHX7y37wuJIzqf3N2TiVXrqfjwugvY/bZ+47EUn78uk6aPZYJGXdDgaFqnIXUV N+hRFYXgKnU0Ui0aQkuYwnAW8KmanLoNU2xodrb6/XqWnSAAmwl7aoGKFunQsT6xDW yQk+ncUHUcdofDUqgd3lXmHGrTmQW97vqexDEnhsJ+AwbLGD5dukr t@test"
}
],
"cloudCredentials": {
"username": "jdoe",
"apikey": "df23gkh34h52gkdgfakgf"
}
}
}
Response
{
"profile": {
"username": "john.doe",
"userId": "12346",
"tenantId": "123456",
"sshkeys": [
{
"name": "t@test",
"publicKey": "ssh-rsa ....."
}
],
"cloudCredentials": {
"username": "jdoe"
},
"links": [
{
"rel": "self",
"href": "https://bigdata.api.rackspacecloud.com/v1.0/123456/profile"
},
{
"rel": "bookmark",
"href": "https://bigdata.api.rackspacecloud.com/123456/profile"
}
]
}
}
Response Code Message 200 Success 400 Malformed data 400 Unacceptable parameters
Flavors
List all available flavors
Verb URI Description Representations GET /flavors List all available flavors JSON, XML
Request
N/A
Response
{
"flavors": [
{
"id": "1",
"name": "hadoop.small",
"ram": "5120MB",
"vcpus": 1,
"disk": "375GB",
"links": [
{
"rel": "self",
"href": "https://bigdata.api.rackspacecloud.com/v1.0/1234/flavors/1"
},
{
"rel": "bookmark",
"href": "https://bigdata.api.rackspacecloud.com/1234/flavors/1"
}
]
},
{
"id": "2",
"name": "hadoop.medium",
"ram": "10240MB",
"vcpus": 2,
"disk": "750GB",
"links": [
{
"rel": "self",
"href": "https://bigdata.api.rackspacecloud.com/v1.0/1234/flavors/2"
},
{
"rel": "bookmark",
"href": "https://bigdata.api.rackspacecloud.com/1234/flavors/2"
}
]
},
{
"id": "3",
"name": "hadoop.large",
"ram": "20480MB",
"vcpus": 4,
"disk": "1500GB",
"links": [
{
"rel": "self",
"href": "https://bigdata.api.rackspacecloud.com/v1.0/1234/flavors/3"
},
{
"rel": "bookmark",
"href": "https://bigdata.api.rackspacecloud.com/1234/flavors/3"
}
]
}
]
}
Response Code Message 200 Success
Get details about a flavor
Verb URI Description Representations GET /flavors/{flavorId} Get details about a flavor JSON, XML
Request
N/A
Response
{
"flavor": {
"id": "1",
"name": "hadoop.small",
"ram": "5120MB",
"vcpus": 1,
"disk": "375GB",
"links": [
{
"rel": "self",
"href": "https://bigdata.api.rackspacecloud.com/v1.0/1234/flavors/1"
},
{
"rel": "bookmark",
"href": "https://bigdata.api.rackspacecloud.com/1234/flavors/1"
}
]
}
}
Response Code Message 200 Success 404 The resource cannot be found
Types
List all available cluster types
Verb URI Description Representations GET /types List all available cluster types JSON, XML
Request
N/A
Response
{
"types": [
{
"id": "HADOOP_HDP1_1",
"name": "Hadoop(HDP1.1)",
"version": 1.1,
"links": [
{
"rel": "self",
"href": "https: //bigdata.api.rackspacecloud.com/v1.0/1234/types/HADOOP_HDP1_1"
},
{
"rel": "bookmark",
"href": "https: //bigdata.api.rackspacecloud.com/1234/types/HADOOP_HDP1_1"
}
]
}
]
}
Response Code Message 200 Success
Get details about a cluster type
Verb URI Description Representations GET /types/{typeId} Get details about a cluster type JSON, XML
Request
N/A
Response
{
"type": {
"name": "HADOOP_HDP1_1",
"version": 1.1,
"services": [
{
"name": "mapreduce",
"version": "1.0.3"
},
{
"name": "hdfs",
"version": "1.0.3"
},
{
"name": "pig",
"version": "0.9.2"
},
{
"name": "hive",
"version": "0.9.0"
}
],
"links": [
{
"rel": "self",
"href": "https://bigdata.api.rackspacecloud.com/v1.0/1234/types/HADOOP_HDP1_1"
},
{
"rel": "bookmark",
"href": "https://bigdata.api.rackspacecloud.com/1234/types/HADOOP_HDP1_1"
}
]
}
}
Response Code Message 200 Success 404 The resource cannot be found
List all the supported flavors for a cluster type
Verb URI Description Representations GET /types/{typeId}/flavors List all the supported flavors for a cluster type JSON, XML
Request
N/A
Response
{
"flavors": [
{
"id": "1",
"name": "hadoop.small",
"ram": "5120MB",
"vcpus": 1,
"disk": "375GB",
"links": [
{
"rel": "self",
"href": "https://bigdata.api.rackspacecloud.com/v1.0/1234/flavors/1"
},
{
"rel": "bookmark",
"href": "https://bigdata.api.rackspacecloud.com/1234/flavors/1"
}
]
},
{
"id": "2",
"name": "hadoop.medium",
"ram": "10240MB",
"vcpus": 2,
"disk": "750GB",
"links": [
{
"rel": "self",
"href": "https://bigdata.api.rackspacecloud.com/v1.0/1234/flavors/2"
},
{
"rel": "bookmark",
"href": "https://bigdata.api.rackspacecloud.com/1234/flavors/2"
}
]
},
{
"id": "3",
"name": "hadoop.large",
"ram": "20480MB",
"vcpus": 4,
"disk": "1500GB",
"links": [
{
"rel": "self",
"href": "https://bigdata.api.rackspacecloud.com/v1.0/1234/flavors/3"
},
{
"rel": "bookmark",
"href": "https://bigdata.api.rackspacecloud.com/1234/flavors/3"
}
]
}
]
}
Response Code Message 200 Success 404 The resource cannot be found
List all the supported cluster types for a flavor
Verb URI Description Representations GET /flavors/{flavorId}/types List all the supported cluster types for a flavor JSON, XML
Request
N/A
Response
{
"type": {
"name": "HADOOP_HDP1_1",
"version": 1.1,
"services": [
{
"name": "mapreduce",
"version": "1.0.3"
},
{
"name": "hdfs",
"version": "1.0.3"
},
{
"name": "pig",
"version": "0.9.2"
},
{
"name": "hive",
"version": "0.9.0"
}
],
"links": [
{
"rel": "self",
"href": "https://bigdata.api.rackspacecloud.com/v1.0/1234/types/HADOOP_HDP1_1"
},
{
"rel": "bookmark",
"href": "https://bigdata.api.rackspacecloud.com/1234/types/HADOOP_HDP1_1"
}
]
}
}
Response Code Message 200 Success 404 The resource cannot be found
Limits
List all the resource limits for the user
Verb URI Description Representations GET /limits List all the resource limits for the user JSON, XML
Request
N/A
Response
{
"limits": {
"absolute": {
"nodeCount": {
"value": 100,
"remaining": 50
},
"ram": {
"value": 50000,
"remaining": 34567
},
"disk": {
"value": 100000,
"remaining": 28882
},
"vcpus": {
"value": 50,
"remaining": 25
}
},
"links": [
{
"rel": "self",
"href": "https://bigdata.api.rackspacecloud.com/v1.0/1234/limits"
},
{
"rel": "bookmark",
"href": "https://bigdata.api.rackspacecloud.com/1234/limits"
}
]
}
}
Response Code Message 200 Success
