Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
426 lines (342 sloc) 13.2 KB
FORMAT: X-1A
HOST: http://0xdata.com/
# H2O REST API
Documentation of H2O REST API.
## General API contracts
- `dst` key should be optional for all requests. If `dst` key is not specified, H2O derives it (i.e., generate UUID) and returns as a part of response
## First class entities (resources)
H2O provides three conceptual resources:
- __Frame__ - a table composed of a header and individual columns. The header contains columns meta-data (e.g., column names, types).
- __Job__ - resource holding a status about an operation (operation can be in progress, done, or cancelled by user or error)
- __Model__ - an entity holding a result of analysis
Here is a link for iris dataset used in example below.
## Allowed HTTPs requests
POST : To create or update resource
GET : Get a resource or list of resources
DELETE : To delete resource
##Description Of Used Server Responses
- 200 `OK` - the request was successful (some API calls may return 201 instead).
- 201 `Created` - the request was successful and a resource was created.
- 204 `No Content` - the request was successful but there is no representation to return (i.e. the response is empty).
- 400 `Bad Request` - the request could not be understood or was missing required parameters.
- 401 `Unauthorized` - authentication failed or user doesn't have permissions for requested operation.
- 403 `Forbidden` - access denied.
- 404 `Not Found` - resource was not found
- 405 `Method Not Allowed` - requested method is not supported for resource.
---
## List files from given datasource [/v2/list_uri.json{?uri,include_filter,exclude_files}]
The call for given URI returns a list of files which are accessible.
The call also returns the files which were skipped (skipped by default, skipped because lack of READ permission,
skipped because of exclude filter or exclude list).
Note: client can filter the list by itself.
+ Parameters
+ uri (string,required) ... uri of data source
+ include_filter = `` (string, optional) ... include files by regexp (basic regexp)
+ exclude_files = `` (string, optional) ... explicit list of excluded files (h2o can put into the list some of files by default)
### Retrieve a list of resources at given URI [GET]
+ Response 200 (application/json)
{
"uris" : [
"hdfs://192.168.1.161/home-0xdiag-datasets/file_1.dat.gz",
"hdfs://192.168.1.161/home-0xdiag-datasets/file_2.dat.gz"
],
"ignored_uris" : [
"hdfs://192.168.1.161/home-0xdiag-datasets/_SUCCESS",
"hdfs://192.168.1.161/home-0xdiag-datasets/_FAILED"
]
}
## Post a file [/v2/post_file.json{?dst,filename}]
The call creates a new primitive value in H2O by uploading a file.
Returns uri (i.e., H2O destination key) of given resource.
```
curl --data-binary @iris.csv http://h2o/v2/post_file.json?filename=iris.csv
```
+ Parameters
+ filename (string, required) ... name of the file which is going to be uploaded
+ dst (string, optional) ... destination key to save file under
### Post a given file [POST]
+ Response 200 (application/json)
{
"dst" : "iris.csv"
}
+ Response 403 (application/json)
{
"error_msg" : "Key already in use!",
"error_code" : 4141
}
## Parse preview [/v2/parse_preview.json?{preview_len}]
The call returns a guessed parser config. The client can explicitly enforce selected parameters/behavior.
```
curl --data-binary\
'{ "parser_config" : {
"uris" : [ "iris.csv" ],
}'\
http://mmalohlava.apiary.io/v2/parse_preview.json
```
The consequents calls should return modified parser configuration according to user' requests.
```
curl --data-binary\
'{ "parser_config" : {
"uris" : [ "iris.csv" ],
"columns" :
[
{
"header" : "sepal_len",
"type" : "DOUBLE"
},
{
"header" : "sepal_wid",
"type" : "DOUBLE"
},
{
"header" : "petal_len",
"type" : "DOUBLE"
},
{
"header" : "petal_wid",
"type" : "DOUBLE"
},
{
"header" : "class",
"type" : "ENUM"
}],
"parser_type" : "CSV",
"header_separator" : ",",
"data_separator" : ",",
"header_file" : "iris.csv"
}
}'\
http://mmalohlava.apiary.io/v2/parse_preview.json?preview_len=10
```
+ Parameters
+ preview_len = `10` (integer,optional) ... length of requested preview
### Retrieve a parse preview [POST]
+ Request (application/json)
+ Parameters
+ parser_config (object) ... parser configuration object
+ uris (list) ... list of strings
+ Body
{
"parsera_config" : {
"uris" : [ "iris.csv" ]
}
}
+ Response 200 (application/json)
{
"parser_config" : {
"uris" : [ "iris.csv" ],
"columns" :
[
{
"header" : "sepal_len",
"type" : "DOUBLE"
},
{
"header" : "sepal_wid",
"type" : "DOUBLE"
},
{
"header" : "petal_len",
"type" : "DOUBLE"
},
{
"header" : "petal_wid",
"type" : "DOUBLE"
},
{
"header" : "class",
"type" : "ENUM"
}],
"parser_type" : "CSV",
"header_separator" : ",",
"data_separator" : ",",
"skip_header" : False,
"header_file" : "iris.csv"
},
"preview_len" : 10,
"preview" : [
[5.1,3.5,1.4,0.2,"Iris-setosa"],
[4.9,3.0,1.4,0.2,"Iris-setosa"],
[4.7,3.2,1.3,0.2,"Iris-setosa"],
[4.6,3.1,1.5,0.2,"Iris-setosa"],
[5.0,3.6,1.4,0.2,"Iris-setosa"],
[5.4,3.9,1.7,0.4,"Iris-setosa"],
[4.6,3.4,1.4,0.3,"Iris-setosa"],
[5.0,3.4,1.5,0.2,"Iris-setosa"],
[4.4,2.9,1.4,0.2,"Iris-setosa"]
]
}
## Get header from file [/v2/get_header?{uri,header_separator}]
The call return a header stored in given file reflecting the separator.
+ Parameters
+ uri (string,required) ... key URI containing a header
+ header_separator (string,optional) ... separator separating header. If the separator is not specified, it is guessed.
### Retrieve a header stored at given URI [GET]
+ Response 200 (application/json)
{
"uri" : "iris.csv",
"header" : [ "sepal_len","sepal_wid","petal_len","petal_wid","class" ],
"header_separator" : ","
}
## Parse [/v2/parse.json]
First call should provide only empty `parser_config` and H2O will return the guessed parser configuration.
I.e.,
```
curl --data-binary\
'{ "parser_config" : {
"uris" : [ "iris.csv" ],
"columns" :
[
{
"header" : "sepal_len",
"type" : "DOUBLE"
},
{
"header" : "sepal_wid",
"type" : "DOUBLE"
},
{
"header" : "petal_len",
"type" : "DOUBLE"
},
{
"header" : "petal_wid",
"type" : "DOUBLE"
},
{
"header" : "class",
"type" : "ENUM"
}],
"parser_type" : "CSV",
"header_separator" : ",",
"data_separator" : ",",
}
}'\
http://mmalohlava.apiary.io/v2/parse.json
```
### Start a parse job [POST]
+ Request (application/json)
{ "parser_config" : {
"uris" : [ "iris.csv" ],
"columns" :
[
{
"header" : "sepal_len",
"type" : "DOUBLE"
},
{
"header" : "sepal_wid",
"type" : "DOUBLE"
},
{
"header" : "petal_len",
"type" : "DOUBLE"
},
{
"header" : "petal_wid",
"type" : "DOUBLE"
},
{
"header" : "class",
"type" : "ENUM"
}],
"parser_type" : "CSV",
"header_separator" : ",",
"data_separator" : ",",
}
}
+ Response 200 (application/json)
{
"dst" : "iris.hex",
"job" : "$0301c0a8013132d4ffffffff$_b1aa57792163146ec3393de65f2b4a6a"
}
+ Response 400 (application/json)
{
"error_msg" : "Missing parameters in parser configuration!",
"error_code" : 0012
}
## Monitor parse progress [/v2/parse_progress.json{?job}]
+ Parameters
+ job (string,required) ... job id returned by parse call
### Monitor parse progress [GET]
+ Response 200 (application/json)
{
"progress" : 0.43,
"status" : "inprogress",
"job" : "$0301c0a8013132d4ffffffff$_b1aa57792163146ec3393de65f2b4a60",
"errors" : [ {
"file": "iris.csv",
"msg" : "The file contains unknown characters"
}
]
}
## Cancel a job [/v2/cancel_job.json{?job}]
Cancel given job.
*This should be part of jobs api as DELETE method*
+ Parameters
+ job (required,string) ... job identification
### Cancel the job [GET]
+ Response 200 (application/json)
{
}
## List available resources [/v2/storeview.json]
### Retrieve [GET]
+ Response 200 (application/json)
{ "resources" : [ {
"type": "model",
"name": "gbm_model",
"uri": "..."
}, {
"type": "frame",
"name": "iris_train.hex",
"uri": "..."
}
]
}
## Inspect a resource [/v2/inspect.json{?src,offset,limit,cols}]
The following section describes Inspect REST call.
+ Parameters
+ src (string,required) ... name of H2O resource
+ offset (number,optional) ... offset of the first required row
+ limit (number,optional) ... number of rows to retrieve
+ cols (string,optional) ... columns selector
### Retrieve [GET]
+ Response 200 (application/json)
{ "src" : "iris_train.hex",
"type" : "frame",
"offset" : 0,
"limit" : 100,
"nrows" : 150,
"ncols" : 5,
"rows" : 3,
}
## Inspect a java [/v2/inspect.java{?src}]
Retrieve a H2O resource as a Java program.
+ Parameters
+ src (string,required) ... name of H2O resource
### Retrieve [GET]
+ Response 200 (plain/text)
class Iris {
}
## Jobs [/v2/jobs]
### Retrieve all jobs [GET]
+ Response 200 (application/json)
{
"jobs": [
{
"name" : "job1",
"dst" : "GBM_model",
"status" : "DONE",
"msg" : null
},
"jobs": [
{
"name" : "job2",
"dst" : "DRF_model",
"status" : "CRASHED",
"msg" : "Assertion: to many trees"
}
]
}
## Frames [/v2/frames]
## Models [/v2/models]