REST API Syntax

Describes the MapR REST API syntax format.

REST calls use the following format to interact with REST API server over the HTTPS protocol: 
https://<host>:<port>/rest/<command>[/<subcommand>...]?<parameters>

In the aforementioned statement, <command> is a maprcli command, and <subcommand> is the command’s subcommand. Refer to the respective command documentation for its subcommands.

Construct the <parameters> list from the required and optional parameters, in the format <parameter>=<value> separated by the ampersand (&) character. Example:

https://r1n1.qa.sj.ca.us:8443/rest/volume/mount?name=test-volume&path=/test
NOTE If used on a command line, the & must be surrounded by quotes, to prevent the shell interpreting it as the background character. Values in REST API calls must be URL-encoded. For readability, the values in this document use the actual characters, rather than the URL-encoded versions.

Authentication

There are 2 main methods to authenticate to REST API, in general:
  • Basic authentication without cookies- Basic authentication is done without cookies
  • Authentication with session cookies - There are three ways of authentication with session cookies.
    • Basic authentication
    • Form-based authentication
    • SPNEGO
      NOTE All methods will use PAM. To configure PAM for REST API, see PAM Configuration.

Basic Authentication without Cookies

To authenticate using basic authentication, send a request with a basic authorization header, which has a user ID and password.
NOTE This method has a higher overhead than session cookies because each request is re-authenticated, due to absence of session cookies.
For example, with cURL and wget:

cURL Syntax

curl -u <username> https://<host>:<port>/rest/<command>...
IMPORTANT To keep your password secure, do not provide it on the command line. Enter your password securely when cURL prompts you for your password.
wget Syntax 
wget --user <username> --ask-password https://<host>:<port>/rest/<command>...
IMPORTANT To keep your password secure, do not provide it on the command line. Use the --ask-password option instead. You can enter your password securely, when wget prompts you for your password.

Authentication with Session Cookies

NOTE Session cookies have an idle time of 30 minutes, that is, they will expire if not used within 30 minutes, and have a maximum lifetime of 24 hours.
To authenticate using basic authentication, send a request with a basic authorization header, which has a user ID and password. For example, run the following command to save cookies into cookiejar.txt, in your home directory: 
curl -u <username> -c ~/cookiejar.txt https://<host>:<port>

To use form based auth to generate a session cookie, send a POST request to /login with the username and password parameters in the form data, for example with curl:

curl -X POST -c ~/cookiejar.txt https://<host>:<port>/login -d 'username=<name>&password=<passwd>'
To authenticate using SPNEGO, ensure that the apiserver nodes are configured for SPNEGO. After configuring, send a negotiate authorization header. For example, to authenticate with the SPNEGO token and save the cookie in a text file named cookiejar.txt in your home directory, run the following command: 
curl --negotiate -u : -b ~/cookiejar.txt -c ~/cookiejar.txt https://<web server node>:8443/rest/<API call> -v

Once the session cookies are generated, the permission of the cookie file must be restricted with the following command:

chmod 600 ~/cookiejar.txt

The contents of the cookie is something similar to the following:

cat /tmp/cookiejar.txt
# Netscape HTTP Cookie File
# https://curl.haxx.se/docs/http-cookies.html
# This file was generated by libcurl! Edit at your own risk.

#HttpOnly_<webserver-hostname>  FALSE  /  TRUE   1509486224  MAPR.APISERVER.JSESSIONID  node014ukard563rhu1ns8umn2s6uft3709.node0
#HttpOnly_<webserver-hostname>  FALSE  /  FALSE  0	    MAPR.APISERVER.SESSIONID   HZA9C20D084E614E36AA567F47FC9105A4

The cookiejar file (session cookie) can now be used to authenticate requests, for example, to retrieve the list of nodes on the cluster with cURL:

curl -sS -b ~/cookiejar.txt https://<host>:<port>/rest/node/list | python -mjson.tool
NOTE In the aforementioned command, -sS and python -mjson.tool are used to obtain well-formatted JSON content.

REST API Calls to Remote Cluster

If you have secure clusters and you wish to make REST API calls to a remote secure cluster, you can specify the cluster parameter in the request if you have your environment configured for remote access. To set up your environment for API calls to remote secure cluster, follow the steps for configuring secure clusters for running commands remotely.