REST API Syntax

Describes the MapR REST API syntax format.

MapR REST calls use the following format: 
https://<host>:<port>/rest/<command>[/<subcommand>...]?<parameters>

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

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

To make REST calls using curl or wget, provide the username and password. To configure PAM for REST API, see PAM Configuration.

Curl Syntax

curl -k -u <username> https://<host>:<port>/rest/<command>...
Warning: To keep your password secure, do not provide it on the command line. Curl will prompt you for your password, and you can enter it securely.

Wget Syntax

wget --no-check-certificate --user <username> --ask-password https://<host>:<port>/rest/<command>...
Warning: To keep your password secure, do not provide it on the command line. Use the --ask-password option instead; then wget will prompt you for your password and you can enter it securely.

To authenticate to the REST interface, use basic authentication or SPNEGO.

Basic Authentication
To authenticate using basic authentication, send a request with a basic authorization header, which has a user ID and password. For example, to authenticate using basic authentication, run the following command: 
curl https://<webserver-hostname>:8443/login -d 'username=root&password=mapr'
On the other hand, if you do not wish to reauthenticate with every request, you can save the cookie and send the cookie with every subsequent request. For example, to authenticate and save the cookie in a text file named cookiejar.txt in /tmp directory, run the following command: 
curl -X POST -c /tmp/cookiejar.txt "https://<webserver-hostname>:8443/login -d" 'username=<name>&password=<pwd>'
To send the cookie with subsequent requests, for example to retrieve the list of nodes on the cluster, you can submit a request similar to the following: 
curl -L -b /tmp/cookiejar.txt "https://<webser-hostname>:8443/rest/node/list/"
SPNEGO
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> -k -v

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

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:

  1. Follow the steps for configuring secure clusters for running commands remotely.
  2. Verify access to run remote commands.
  3. Rename the ticket file generated using the maprlogin password command to mapruserticket and move the file to /opt/mapr/conf directory.
Parent topic: Overview