This is a standard CMake project which may be built with either Ninja or Make.

This code base is built with the iRODS toolchain, which uses Clang. Since this project depends on Pistache, we also need to build Pistache with Clang in order to link against that project.

First clone the iRODS externals repository.

git clone https://github.com/irods/externals
git checkout 4-2-stable

Install the latest iRODS CMake and Clang packages

irods-cmake
irods-externals-clang-runtime
irods-externals-clang

Then within the externals repository, build Pistache with

make pistache

Then install Pistache with

cd pistache<VERSION>-0_src/pistache/build/
make install

You will then need to install iRODS packages

irods-dev
irods-runtime
irods-externals-boost
irods-externals-json

Once this is done you can create a build directory for the REST API and run CMake, then run

make package

to build the REST API package.

The REST API provides an executable for each individual API endpoint. These endpoints may be grouped behind a reverse proxy in order to provide a single port for access.

The services rely on a configuration file in /etc/irods/ which dictates which ports are used for each service. Two template files are placed there by the package:

/etc/irods/irods_client_rest_cpp.json.template
/etc/irods/irods-client-rest-cpp-reverse-proxy.conf.template

/etc/irods/irods_client_rest_cpp.json.template should be copied to /etc/irods/irods_client_rest_cpp.json and modified if different ports are desired. The service can then be restarted with service irods_client_rest_cpp restart, or however your specific platform manages services.

Once the REST API is running install nginx and then copy /etc/irods/irods-client-rest-cpp-reverse-proxy.conf.template to /etc/nginx/sites-available/irods-client-rest-cpp-reverse-proxy.conf and then symbolically link it to /etc/nginx/sites-enabled/irods-client-rest-cpp-reverse-proxy.conf. Nginx will then need to be restarted with sudo service nginx restart, or however your specific platform manages services.

The design of this API using JWTs to contain authorization and identity. The Auth endpoint must be invoked first in order to authenticate and receive a JWT. This token will then need to be included in the Authorization header of each subsequent request. This API follows a HATEOAS design which provides not only the requested information but possible next operations on that information.

This endpoint provides a service for the generation of an iRODS ticket to a given logical path, be that a collection or a data object.

Method : POST

Parameters:

• path: The url encoded logical path to a collection or data object for which access is desired

Example CURL Command:

curl -X POST -H "Authorization: ${TOKEN}" "http://localhost/irods-rest/1.0.0/access?path=%2FtempZone%2Fhome%2Frods%2Ffile0"

Returns

An iRODS ticket token within the X-API-KEY header, and a URL for streaming the object.

{
  "headers": [
    "X-API-KEY: CS11B8C4KZX2BIl"
  ],
  "url": "/irods-rest/1.0.0/stream?path=%2FtempZone%2Fhome%2Frods%2Ffile0&offset=0&limit=33064"
}

The administration interface to the iRODS Catalog which allows the creation, removal and modification of users, groups, resources, and other entities within the zone.

Method : POST

Parameters

• action : dictates the action taken: add, modify, or remove
• target : the subject of the action: user, zone, resource, childtoresc, childfromresc, token, group, rebalance, unusedAVUs, specificQuery
• arg2 : generic argument, could be user name, resource name, depending on the value of action and target
• arg3 : generic argument , see above
• arg4 : generic argument , see above
• arg5 : generic argument , see above
• arg6 : generic argument , see above
• arg7 : generic argument , see above

Example CURL Command:

curl -X POST -H "Authorization: ${TOKEN}" "http://localhost/irods-rest/1.0.0/admin?action=add&target=resource&arg2=ufs0&arg3=unixfilesystem&arg4=/tmp/irods/ufs0&arg5=&arg6=tempZone"

Returns

"Success" or an iRODS exception

This endpoint provides an authentication service for the iRODS zone, currently only native iRODS authentication is supported.

Method : POST

Parameters:

• Authorization Header of the form Authorization: Basic ${SECRETS} where ${SECRETS} is a base 64 encoded string of user_name:password

Example CURL Command:

export SECRETS=$(echo -n rods:rods | base64)
export TOKEN=$(curl -X POST -H "Authorization: Basic ${SECRETS}" http://localhost:80/irods-rest/1.0.0/auth)

Returns:

An encrypted JWT which contains everything necessary to interact with the other endpoints. This token is expected in the Authorization header for the other services.

This endpoint will return a JSON structure holding the configuration for an iRODS server

Method : GET

Parameters

• None

Example CURL Command:

curl -X GET -H "Authorization: ${TOKEN}" "http://localhost/irods-rest/1.0.0/get_configuration" | jq

This endpoint provides a recursive listing of a collection, or stat, metadata, and access control information for a given data object.

Method : GET

Parameters

• path : The url encoded logical path which is to be listed
• stat : Boolean flag to indicate stat information is desired
• permissions : Boolean flag to indicate access control information is desired
• metadata : Boolean flag to indicate metadata is desired
• offset : number of records to skip for pagination
• limit : number of records desired per page

Example CURL Command:

curl -X GET -H "Authorization: ${TOKEN}" "http://localhost/irods-rest/1.0.0/list?path=%2FtempZone%2Fhome%2Frods&stat=0&permissions=0&metadata=0&offset=0&limit=100" | jq

Returns

A JSON structured response within the body containing the listing, or an iRODS exception

{
  "_embedded": [
    {
      "logical_path": "/tempZone/home/rods/subcoll",
      "type": "collection"
    },
    {
      "logical_path": "/tempZone/home/rods/subcoll/file0",
      "type": "data_object"
    },
    {
      "logical_path": "/tempZone/home/rods/subcoll/file1",
      "type": "data_object"
    },
    {
      "logical_path": "/tempZone/home/rods/subcoll/file2",
      "type": "data_object"
    },
    {
      "logical_path": "/tempZone/home/rods/file0",
      "type": "data_object"
    }
  ],
  "_links": {
    "first": "/irods-rest/1.0.0/list?path=%2FtempZone%2Fhome%2Frods&stat=0&permissions=0&metadata=0&offset=0&limit=100",
    "last": "/irods-rest/1.0.0/list?path=%2FtempZone%2Fhome%2Frods&stat=0&permissions=0&metadata=0&offset=UNSUPPORTED&limit=100",
    "next": "/irods-rest/1.0.0/list?path=%2FtempZone%2Fhome%2Frods&stat=0&permissions=0&metadata=0&offset=100&limit=100",
    "prev": "/irods-rest/1.0.0/list?path=%2FtempZone%2Fhome%2Frods&stat=0&permissions=0&metadata=0&offset=0&limit=100",
    "self": "/irods-rest/1.0.0/list?path=%2FtempZone%2Fhome%2Frods&stat=0&permissions=0&metadata=0&offset=0&limit=100"
  }
}

This endpoint will write the url encoded JSON to the specified files in /etc/irods

Method : PUT

Parameters

• cfg : a url encoded json string of the format

[
    {
        "file_name":"test_rest_cfg_put_1.json",
        "contents" : {
            "key0":"value0",
            "key1" : "value1"
        }
    },
    {
        "file_name":"test_rest_cfg_put_2.json",
        "contents" : {
            "key2" : "value2",
            "key3" : "value3"
        }
    }
]

Example CURL Command:

export CONTENTS="%5B%7B%22file_name%22%3A%22test_rest_cfg_put_1.json%22%2C%20%22contents%22%3A%7B%22key0%22%3A%22value0%22%2C%22key1%22%20%3A%20%22value1%22%7D%7D%2C%7B%22file_name%22%3A%22test_rest_cfg_put_2.json%22%2C%22contents%22%3A%7B%22key2%22%20%3A%20%22value2%22%2C%22key3%22%20%3A%20%22value3%22%7D%7D%5D"
curl -X PUT -H "Authorization: ${TOKEN}" "http://localhost/irods-rest/1.0.0/put_configuration?cfg=${CONTENTS}"

Returns Nothing on success

This endpoint provides access to the iRODS General Query language, which is a generic query service for the iRODS catalog.

Method : GET

Parameters

• query_string : A url encoded general query
• query_limit : Number of desired rows
• row_offset : Number of rows to skip for paging
• query_type : Either 'general' or 'specific'

Example CURL Command:

curl -X GET -H "Authorization: ${TOKEN}" "http://localhost/irods-rest/1.0.0/query?query_limit=100&row_offset=0&query_type=general&query_string=SELECT%20COLL_NAME%2C%20DATA_NAME%20WHERE%20COLL_NAME%20LIKE%20%27%2FtempZone%2Fhome%2Frods%25%27" | jq

Returns A JSON structure containing the query results

{
  "_embedded": [
    [
      "/tempZone/home/rods",
      "file0"
    ],
    [
      "/tempZone/home/rods/subcoll",
      "file0"
    ],
    [
      "/tempZone/home/rods/subcoll",
      "file1"
    ],
    [
      "/tempZone/home/rods/subcoll",
      "file2"
    ]
  ],
  "_links": {
    "first": "/irods-rest/1.0.0query?query_string=SELECT%20COLL_NAME%2C%20DATA_NAME%20WHERE%20COLL_NAME%20LIKE%20%27%2FtempZone%2Fhome%2Frods%25%27&query_limit=100&row_offset=0&query_type=general",
    "last": "/irods-rest/1.0.0query?query_string=SELECT%20COLL_NAME%2C%20DATA_NAME%20WHERE%20COLL_NAME%20LIKE%20%27%2FtempZone%2Fhome%2Frods%25%27&query_limit=100&row_offset=0&query_type=general",
    "next": "/irods-rest/1.0.0query?query_string=SELECT%20COLL_NAME%2C%20DATA_NAME%20WHERE%20COLL_NAME%20LIKE%20%27%2FtempZone%2Fhome%2Frods%25%27&query_limit=100&row_offset=0&query_type=general",
    "prev": "/irods-rest/1.0.0query?query_string=SELECT%20COLL_NAME%2C%20DATA_NAME%20WHERE%20COLL_NAME%20LIKE%20%27%2FtempZone%2Fhome%2Frods%25%27&query_limit=100&row_offset=0&query_type=general",
    "self": "/irods-rest/1.0.0query?query_string=SELECT%20COLL_NAME%2C%20DATA_NAME%20WHERE%20COLL_NAME%20LIKE%20%27%2FtempZone%2Fhome%2Frods%25%27&query_limit=100&row_offset=0&query_type=general"
  },
  "count": "4",
  "total": "4"
}

Stream data into and out of an iRODS data object

Method : GET and PUT

Parameters

• path : The url encoded logical path to a data object
• offset : The offset in bytes into the data object
• limit : The maximum number of bytes to read

Returns

PUT : Nothing, or iRODS Exception

GET : The data requested in the body of the response

Example CURL Command:

curl -X PUT -H "Authorization: ${TOKEN}" -d"This is some data" "http://localhost/irods-rest/1.0.0/stream?path=%2FtempZone%2Fhome%2Frods%2FfileX&offset=0&limit=1000"

or

curl -X GET -H "Authorization: ${TOKEN}" "http://localhost/irods-rest/1.0.0/stream?path=%2FtempZone%2Fhome%2Frods%2FfileX&offset=0&limit=1000"

Requests a JSON formatted iRODS Zone report, containing all configuration information for every server in the grid.

Method : POST

Parameters

• None

Example CURL Command:

curl -X POST -H "Authorization: ${TOKEN}" "http://localhost/irods-rest/1.0.0/zone_report" | jq

Returns JSON formatted Zone Report

{
  "schema_version": "file:///var/lib/irods/configuration_schemas/v3/zone_bundle.json",
  "zones": [
    {
    <snip>
    }]
}