IBM Support

Introducing RSE API

News


Abstract

Remote System Explorer API to access IBM i resources using REST APIs

Content

You are in: Welcome to IBM RSE API for i Technology Updates >  Introducing RSE API

What is it?

The Remote System Explorer (RSE) API is a web application that provides REST APIs for IBM i services covering database files, IFS files, CL commands and several other IBM i services.  It can be used by any user that has a user profile on the target IBM i server.
The RSE API web application runs in the admin5 integrated application server (IAS), a server that is part of the IBM Web Administration set of servers.  The following figure shows the general flow between web clients and the RSE API application deployed in the application server.
image-20230410171142-1

The flow is as follows:

  1. Clients make requests. Requests are routed to the RSE API application.
  2. The RSE API performs the requested operation and returns the response in JSON format.  The target IBM i server can be a remote IBM i server or the IBM i server that the RSE API application is running on.

The RSE APIs can be categorized as follows:

  • Administrative Services
    Get information about the state of the RSE API environment, such as number of sessions, memory usage, and set global RSE API settings. Only users who connect to localhost and have been designated as administrators or have *ALLOBJ authority are able to successfully invoke the Administrative Services APIs.
  • Session Services
    Session services are used to authenticate and manage sessions.
  • CL Command Service
    The CL command service is used to run CL commands.
  • IFS Services
    The IFS services are used to perform IFS operations such as listing directory contents, reading from a file, and writing to a file.
  • QSYS Service
    The QSYS service allows users to search for QSYS objects.
  • Server Information Service
    The server information services retrieve information about the RSE API application version.
  • SQL Service
    The SQL service API allows you to run SQL statements.
Authentication
All API requests must be submitted over a secure connection (https).  An API request over an unsecure connection will fail. If indirectly accessing an IBM i server, the host servers on that server need to be configured for TLS.
In order for RSE API to be used, authenticate using the POST HTTP method using the session API. If authentication is successful, a token is returned in the Authorization HTTP header. The client must send the token in the Authorization header when making requests to other APIs.  An example of an HTTP header:
Authorization: Bearer 4eaa14e6-ea9c-4dde-b6f7-f542b34d5309-60da75d3-3132
Alternatively, a request can be sent to an API (except session APIs) with HTTP basic authentication.  The request is authenticated, and the API is then invoked and the response is returned.  No token is returned.
Errors
RSE API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.). Codes in the 5xx range indicate an internal error with RSE API.
If an error is encountered, the following JSON response is returned (the following is an example of an error):
 
{  
   "title": "BAD_REQUEST",
   "status": 400,
   "detail": "Path name not set.",
   "method": "GET",
   "instance": "/rseapi/api/v1/ifs/list",
   "timestamp": "2022-02-20T14:51:58.252Z"
}
where:
  • title is a string representing the HTTP status code description.
  • status is an integer representing the HTTP status code.
  • detail is a human readable string that provides more details about the error. 
  • method is a string that represents the HTTP method that was used in the request.
  • instance is a string that represents the URI that was used in the request.
  • timestamp is a string that represents a timestamp of when the error occurred in ISO-8601 format.
Getting started
Assuming you have the IBM Web Administration Server active, you can view the online documentation by specifying the following URL: http://host:2011/openapi/ui/, where host is your IBM i host name.  However, if you want to use the APIs and see the request and response data without having to develop an application that uses the APIs, you have to enable TLS for the admin5 server and use the following URL: https://host:2012/openapi/ui/.

Why use it?

Use RSE API to interact with IBM i resources via REST APIs. You can issue commands, search for objects, access IFS files, and run SQL statements.
 

Availability

The support is enabled in the following PTFs:
V7R5M0 SI83125
V7R4M0 SI83126
V7R3M0 SI83127

[{"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Product":{"code":"HW1A1","label":"IBM Power Systems"},"Component":"","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"All Versions","Edition":"","Line of Business":{"code":"LOB57","label":"Power"}}]

Document Information

Modified date:
11 April 2023

UID

ibm16982805

Page Feedback