Note: This repository has been deprecated and archived.
Please find the new HTTP API implementation at:
https://github.com/irods/irods_client_http_api
This REST API is designed to be deployed in front of an iRODS Server to provide an HTTP REST interface into the iRODS protocol.
This REST API requires an iRODS Server v4.2.0 or greater.
The iRODS C++ REST API can be installed via package manager and managed via systemctl alongside an existing iRODS Server:
# REST API - install
$ sudo apt install irods-client-rest-cpp
OR
$ sudo yum install irods-client-rest-cpp
nginx, rsyslog, and logrotate can be configured and restarted before starting the REST API:
# nginx - configure and restart
$ sudo cp /etc/irods_client_rest_cpp/irods_client_rest_cpp_reverse_proxy.conf.template /etc/nginx/sites-available/irods_client_rest_cpp_reverse_proxy.conf
$ sudo ln -s /etc/nginx/sites-available/irods_client_rest_cpp_reverse_proxy.conf /etc/nginx/sites-enabled/irods_client_rest_cpp_reverse_proxy.conf
$ sudo rm /etc/nginx/sites-enabled/default
$ sudo systemctl restart nginx
# rsyslog - configure and restart
$ sudo cp /etc/irods_client_rest_cpp/irods_client_rest_cpp.conf.rsyslog /etc/rsyslog.d/00-irods_client_rest_cpp.conf
$ sudo cp /etc/irods_client_rest_cpp/irods_client_rest_cpp.logrotate /etc/logrotate.d/irods_client_rest_cpp
$ sudo systemctl restart rsyslog
# REST API - configure and start
$ sudo cp /etc/irods_client_rest_cpp/irods_client_rest_cpp.json.template /etc/irods_client_rest_cpp/irods_client_rest_cpp.json
$ sudo systemctl restart irods_client_rest_cpp
This is a standard CMake project which may be built with either Ninja or Make.
This project depends on irods-dev(el) and irods-runtime version 4.3.0 (available from https://packages.irods.org). The minimum required CMake is 3.12.0. You can install the latest irods-externals-cmake package if needed (also available from https://packages.irods.org).
Once these are installed, the other irods-externals-* versions will be revealed through building with cmake and may change over time as this code base develops.
Prerequisites (available from https://packages.irods.org):
irods-dev(el)
irods-runtime
irods-externals-boost
irods-externals-clang
irods-externals-json
irods-externals-pistache
irods-externals-spdlog
Create and enter a build directory, run CMake (make sure it is visible in your $PATH), and then make the REST API package:
$ mkdir build && cd build
$ cmake -DIRODS_BUILD_WITH_WERROR=NO ..
$ make -j package
Note: For machines with fewer than 4 cores or heavy workloads, building using the -j option with make should be done with caution. Refer to the manual for more information on this topic: https://www.gnu.org/software/make/manual/make.html#Parallel-Execution
This repository provides a Dockerfile with all of the tools needed to build a package for Ubuntu 20.04.
The builder image itself must first be built. This can be done by running the following:
$ cd docker/builder
$ docker build -t irods-client-rest-cpp-builder:ubuntu-20.04 .This will produce a Docker Image with tag irods-client-rest-cpp-builder:ubuntu-20.04. The tag can be anything, as long as it is used consistently.
Once built, the builder can be run to build packages from source code on the host machine. The script run by the container takes the following inputs:
- A volume mount for the source directory (this repository) on the host
- A volume mount for the output build files on the host
- A volume mount for the package by itself on the host
Here is an example usage:
docker run -t --rm \
-v ${sourcedir}:/src:ro \
-v ${builddir}:/build \
-v ${packagedir}:/packages \
irods-client-rest-cpp-builder:ubuntu-20.04$sourcedir, $builddir, and $packagedir should be full paths to the source code directory, the desired output directory for build artifacts, and the desired output directory for the built package.
Once the build has completed, you should find a .deb file on the host machine where you specified $packagedir to be.
Integrating this into your workflow is an exercise left to the reader.
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 service relies on a configuration file in /etc/irods_client_rest_cpp which dictates which ports are used. Two template files are placed there by the package:
/etc/irods_client_rest_cpp/irods_client_rest_cpp.json.template
/etc/irods_client_rest_cpp/irods_client_rest_cpp_reverse_proxy.conf.templateTo start the REST API service, run the following commands:
$ sudo cp /etc/irods_client_rest_cpp/irods_client_rest_cpp.json.template /etc/irods_client_rest_cpp/irods_client_rest_cpp.json # configuration
$ sudo systemctl start irods_client_rest_cpp # start the serviceIf everything was successful, you now have a functional REST API service.
If you modify the configuration file (i.e. port numbers, log level, etc.). You'll need to restart the service for the changes to take affect.
This section assumes you have a functional REST API service.
The first thing you must do is install nginx. Once installed, run the following commands to enable the reverse proxy:
$ sudo cp /etc/irods_client_rest_cpp/irods_client_rest_cpp_reverse_proxy.conf.template /etc/nginx/sites-available/irods_client_rest_cpp_reverse_proxy.conf # configuration
$ sudo ln -s /etc/nginx/sites-available/irods_client_rest_cpp_reverse_proxy.conf /etc/nginx/sites-enabled/irods_client_rest_cpp_reverse_proxy.conf # configuration
$ sudo systemctl restart nginx # start the serviceIf you modified any port numbers in the REST API's configuration file, you will need to adjust the reverse proxy's configuration file so that nginx can connect to the correct endpoint.
If you are getting a 404 error from the reverse proxy, make sure to remove the default file from /etc/nginx/sites-enabled directory. This default site may be listening on the same port as your reverse proxy and preventing the requests from reaching it.
This section assumes you've installed the C++ REST API package.
If you are doing a non-package install, you'll need to copy the configuration files from the repository to the appropriate directories and restart rsyslog. The files of interest and their destinations are shown below.
The REST API uses rsyslog and logrotate for log file management. To enable, run the following commands:
$ sudo cp /etc/irods_client_rest_cpp/irods_client_rest_cpp.conf.rsyslog /etc/rsyslog.d/00-irods_client_rest_cpp.conf
$ sudo cp /etc/irods_client_rest_cpp/irods_client_rest_cpp.logrotate /etc/logrotate.d/irods_client_rest_cpp
$ sudo systemctl restart rsyslogThe log file will be located at /var/log/irods_client_rest_cpp/irods_client_rest_cpp.log.
The log level for each endpoint can be adjusted by modifying the "log_level" option in /etc/irods_client_rest_cpp/irods_client_rest_cpp.json. The following values are supported:
- trace
- debug
- info
- warn
- error
- critical
It is highly advised to run the service with HTTPS enabled. The administrative API endpoint (i.e. /admin) is implemented to accept passwords in plaintext. This is on purpose as it removes the password obfuscation requirements from applications built upon the C++ REST API.
Please refer to your proxy server's (nginx, apache httpd, etc.) documentation for enabling SSL communication.
This repository provides a Docker Compose project which runs a local iRODS C++ REST client package in an Ubuntu 20.04-based container alongside an nginx reverse-proxy service.
To run, the following things will be required:
- A
.debpackage built for Ubuntu 20.04 residing on the filesystem of the local host (see Building with Docker). - An iRODS server reachable by the containers providing the Compose project services on the host machine.
The Compose project is found under docker/runner along with the attendant files.
Copy the .deb package into docker/runner (i.e. cp /path/to/package.deb ./docker/runner). The package will be installed as part of the Docker image built for the REST client service. If you are having trouble, check to make sure that the name of the file you copied matches the local_package build argument under the irods-client-rest-cpp service definition in the ./docker/runner/docker-compose.yml file.
You will also need to modify ./docker/runner/irods_client_rest_cpp.json to match the desired iRODS client environment. You may also wish to change the jwt_signing_key outside of an experimental context.
Now that things are set up, let's run it:
cd ./docker/runner
docker-compose up
The nginx and REST client service Docker images should be built and then containers spawned for each service. The nginx service exposes port 80 on the host machine by default. If you wish to change this, edit the ./docker/runner/docker-compose.yml file and restart the service. Note: The ports for the REST services are not exposed on the host machine - only the nginx reverse-proxy port is exposed.
To stop the service:
docker-compose down
To modify configuration settings for the REST services, edit the ./docker/runner/irods_client_rest_cpp.json file on the host machine and restart the services:
docker-compose restart
The design of this API uses 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.
Unless otherwise specified, successful operations by this client should return with an empty body. If some error is reported, it will follow this format:
{
"error_code": integer,
"error_message": string
}The administration interface to the iRODS Catalog which allows the creation, removal and modification of users, groups, resources, and other entities within the zone. ALL input parameters must be defined. If an input parameter is not to be used, set it to nothing (e.g. arg7=)
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
actionandtarget - 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/0.9.4/admin?action=add&target=resource&arg2=ufs0&arg3=unixfilesystem&arg4=/tmp/irods/ufs0&arg5=&arg6=tempZone&arg7='
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/0.9.4/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/0.9.4/get_configuration' | jq