Getting Started with the HPE Ezmeral Data Fabric Database JSON REST API

A simple way to invoke the HPE Ezmeral Data Fabric Database JSON REST API is to use cURL commands. This section contains a sequence cURL commands that demonstrate the basic functionality of the API.

Note: The HPE Ezmeral Data Fabric Database JSON REST API is available starting in the MEP 5.0 release.

The operations shown are the following:

Create a HPE Ezmeral Data Fabric Database JSON table
Insert documents into the table
Retrieve documents from the table, including retrievals that contain field projections and conditions
Update individual documents and fields within a document

To learn about the complete API, see the reference material at Understanding the HPE Ezmeral Data Fabric Database JSON REST API.

The examples in this section assume that you installed the MapR Data Access Gateway on the host 10.10.100.42. The examples use HTTPS with the default HTTPS port of 8243. For information about installing the Data Access Gateway, see Installing the Data Access Gateway Service.

Note: The examples URL encode the slashes in the table path (%2F) to differentiate them from the slashes in the command API.

Using Basic Authentication

The commands in this section use basic authentication. To use this form of authentication, you must pass the username and password in all commands, using the -u option.

Create a HPE Ezmeral Data Fabric Database JSON table in the path /apps/employees:

curl -X PUT \
  'https://10.10.100.42:8243/api/v2/table/%2Fapps%2Femployees' \
  -u root:mapr

Insert 3 documents into the table:

curl -X POST \
  'https://10.10.100.42:8243/api/v2/table/%2Fapps%2Femployees' \
  -u root:mapr \
  -H 'Content-Type: application/json' \
  -d '[{"_id":"user001","first_name":"John","last_name":"Doe"},
 {"_id":"user002","first_name":"Jane","last_name":"Doe"},
 {"_id":"user003","first_name":"Simon","last_name":"Davis"}]'

Retrieve all of the documents:

curl -X GET \
  'https://10.10.100.42:8243/api/v2/table/%2Fapps%2Femployees%2F' \
  -u root:mapr

The command returns the following:

{
    "DocumentStream": [
        {
            "_id": "user001",
            "first_name": "John",
            "last_name": "Doe"
        },
        {
            "_id": "user002",
            "first_name": "Jane",
            "last_name": "Doe"
        },
        {
            "_id": "user003",
            "first_name": "Simon",
            "last_name": "Davis"
        }
    ]
}

Limit the GET request to 2 documents starting at offset 1:

curl -X GET \
  'https://10.10.100.42:8243/api/v2/table/%2Fapps%2Femployees%2F?offset=1&limit=2' \
  -u root:mapr

The command returns the following:

{
    "DocumentStream": [
        {
            "_id": "user002",
            "first_name": "Jane",
            "last_name": "Doe"
        },
        {
            "_id": "user003",
            "first_name": "Simon",
            "last_name": "Davis"
        }
    ]
}

Retrieve only the first names in the documents:

curl -X GET \
'https://10.10.100.42:8243/api/v2/table/%2Fapps%2Femployees?fields=first_name' \
  -u root:mapr

The command returns the following:

{
    "DocumentStream": [
        {
            "first_name": "John"
        },
        {
            "first_name": "Jane"
        },
        {
            "first_name": "Simon"
        }
    ]
}

Retrieve all documents with a last name of 'Doe':

curl -g -X GET \
'https://10.10.100.42:8243/api/v2/table/%2Fapps%2Femployees?condition={"$eq":{"last_name":"Doe"}}' \
  -u root:mapr

Note: You must pass '-g' in the cURL command due to the nested braces in the condition.

The command returns 2 documents:

{
    "DocumentStream": [
        {
            "_id": "user001",
            "first_name": "John",
            "last_name": "Doe"
        },
        {
            "_id": "user002",
            "first_name": "Jane",
            "last_name": "Doe"
        }
    ]
}

Retrieve the id and first name of documents with a last name of 'Doe':

curl -g -X GET \
'https://10.10.100.42:8243/api/v2/table/%2Fapps%2Femployees?condition={"$eq":{"last_name":"Doe"}}&fields=_id,first_name' \
  -u root:mapr

Note: You must pass '-g' in the cURL command due to the nested braces in the condition.

The command returns the following:

{
    "DocumentStream": [
        {
            "_id": "user001",
            "first_name": "John"
        },
        {
            "_id": "user002",
            "first_name": "Jane"
        }
    ]
}

Run the same command, also retrieving the query plan:

curl -g -X GET \
'https://10.10.100.42:8243/api/v2/table/%2Fapps%2Femployees?condition={"$eq":{"last_name":"Doe"}}&fields=_id,first_name&getPlan=true' \
  -u root:mapr

The output includes the query plan:

{
    "DocumentStream": [
        {
            "_id": "user001",
            "first_name": "John"
        },
        {
            "_id": "user002",
            "first_name": "Jane"
        }
    ],
    "QueryPlan": [
        [
            {
                "streamName": "DBDocumentStream",
                "parameters": {
                    "queryConditionPath": true,
                    "projectionPath": [
                        "_id",
                        "first_name"
                    ],
                    "primaryTable": "/apps/employees"
                }
            }
        ]
    ]
}

Update the first name in one of the documents, specifying the id in the command:

curl -X POST \
'https://10.10.100.42:8243/api/v2/table/%2Fapps%2Femployees/document/user001' \
  -H 'Content-Type: application/json' \
  -u root:mapr \
  -d '{"$set":{"first_name":"Jay"}}'

Retrieve the updated document, specifying the id in the command:

curl -X GET \
'https://10.10.100.42:8243/api/v2/table/%2Fapps%2Femployees/document/user001' \
  -u root:mapr

The document contains an updated first name:

{
    "_id": "user001",
    "first_name": "Jay",
    "last_name": "Doe"
}

Replace the same document, but this time with a user who has only a first name:

curl -X PUT \
'https://10.10.100.42:8243/api/v2/table/%2Fapps%2Femployees/document/user001' \
  -H 'Content-Type: application/json' \
  -u root:mapr \
  -d '{"_id":"user001","first_name":"Jonathan"}'

Retrieve the new document by passing the id in the request:

curl -X GET \
'https://10.10.100.42:8243/api/v2/table/%2Fapps%2Femployees/document/user001' \
  -u root:mapr

The document contains only a first name:

{
    "_id": "user001",
    "first_name": "Jonathan"
}

Using Token-Based Authentication

To use token-based authentication, you first create a token, authenticating with a username and password. You then pass the generated token in all subsequent commands.

Generate a token using the following command:

curl -X POST \
  'https://10.10.100.42:8243/auth/v2/token' \
  -u root:mapr

The command returns the following token:

{
    "token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJyb290IiwiYXVkIjoid2ViIiwiZXhwIjoxNTIwMjY5MTQwLCJpYXQiOjE1MjAyNjczNDB9.NT8L2deiA6v55bfbU_opiG1XXGPP0IwfSex3jW5A1ZsoI1ar09it7-XwNtRqfL_I29IHLyfmuHcT5eSIpwq6ng"
}

Pass the token in your cURL command, as shown in the following GET:

curl -X GET \
  https://10.10.100.42:8243/api/v2/table/%2Fapps%2Femployees \
  -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJyb290IiwiYXVkIjoid2ViIiwiZXhwIjoxNTIwMjY5MTQwLCJpYXQiOjE1MjAyNjczNDB9.NT8L2deiA6v55bfbU_opiG1XXGPP0IwfSex3jW5A1ZsoI1ar09it7-XwNtRqfL_I29IHLyfmuHcT5eSIpwq6ng'