REST API Version 1
Accessing the application.wadl File
The application.wadl file is located at http(s)://server:port/grid/application.wadl.
-
Open one of the supported browsers.
-
Navigate to the following URL: http(s)://server:port/grid/application.wadl where server is the name of the server hosting the grid and port is the HTTP or HTTPS port for the grid router.
Security
Most of the exposed REST services that use the HTTP POST method will require authentication. Authentication may be performed using username/password or certificates. For information about how to generate a client certificate, see the Infor ION Grid Security Administration Guide.
REST Services Exposed by the ION Grid
The available REST services are shown in the tables below. Note that the REST services that use the HTTP GET method can easily be tested from any web browser. For example, assume that the router that exposes an HTTP port on the following address: http://server:20005. In this case, you can call the following from any browser:
-
http://server:20005/grid/status
-
http://server:20005/grid/nodes
-
and so on
Grid-wide REST Services
| Resource | Type | Description | Sample Path |
|---|---|---|---|
| info | GET | This document contains basic grid version information and context roots defined by applications installed into the grid. | /grid/info |
| status | GET | The status document contains an entry for each deployed application. The information for each application contains such things as global status, log warnings and error counts, memory status, CPU status, and offline state. | /grid/status |
| hosts | GET | This returns status information for hosts that are part of the grid. Information examples are OS version, system time, offline state, and memory usage. | /grid/hosts |
| ports | GET | This returns information about all ports used by the grid and what purpose they serve. | /grid/ports |
| bindings | GET | This returns information about all bindings that are defined in the grid. This information may be used when starting nodes using the startnode service: /grid/host/hostName/startnode?binding=bindingName | /grid/bindings |
| nodes | GET | This returns status information for all running nodes, routers, and the registry. The returned information includes, for example, log warning and error counts, memory usage, CPU usage, and offline state. | /grid/nodes |
| offline | POST | Puts the grid in an offline state. | /grid/offline |
| online | POST | Puts the grid in an online state. | /grid/online |
| stop | POST | Stops the grid with the given grace period and reason. |
/grid/stop /grid/ stop?graceSeconds=20 &reason=reasonDescription&deactivate=false (true would mean deactivation of the Grid and explicit start would be required using Bootstrap control scripts) |
| resetLogCounters | POST | Resets the log counters for the grid. | /grid/resetLogCounters |
| user | GET | Returns all session related information including session ID, current serving node, grid principal information, HTTP header(s). | /grid/user |
| usersession | GET | Returns the current user's session information if it exists. | /grid/usersession |
Host-related REST Services
| Resource | Type | Description | Sample Path |
|---|---|---|---|
| offline | POST | Puts the host in an offline state. | /grid/host/hostName/offline |
| online | POST | Puts the host in an online state. | /grid/host/hostName/online |
| startnode | POST | Starts the node using a specified binding on the specified host. | /grid/host/hostName/startnode?binding=bindingName |
| stop | POST | Stops the Grid Host. | /grid/host/hostName/stop /grid/host/hostName/stop?grace=20&async=false (grace period to allow application nodes to end normally before carrying out immediate end; wait for operation to complete (sync) or issue operation and return (async)) |
Application-related REST Services
| Resource | Type | Description | Sample Path |
|---|---|---|---|
| start | POST | Starts the specified application. Optionally, you can specify if the application should be put in an offline state after starting it. | /grid/application/appName/start?offline=false |
| stop | POST | Stops the specified application. Optionally, you can specify if the application should be put in an offline state after stopping it. Also, it is possible to say that the call should block until the application has stopped completely, that the application shall remain permanently offline and to define a grace period to wait for the application to shutdown normally before carrying out immediate shutdown. | /grid/application/appName/stop?offline=true&block=true&permanentlyOffline=true&graceSeconds=60 |
| offline | POST | Puts the specified application in an offline state. |
/grid/application/appName/offline /grid/application/appName/ offline?permanentlyOffline=true |
| online | POST | Puts the specified application in an online state. | /grid/application/appName/online |
| status | GET | Return status information for the specified application. The returned information includes the global state and offline state as well as status information for each grid node that belongs to this application and information for each host that the application is deployed on. | /grid/application/appName/status |
Node-related REST Services
| Resource | Type | Description | Sample Path |
|---|---|---|---|
| log | GET |
Returns the log file for the specified node (nodes are identified by their JVM ID). Optionally, the log may be filtered on a supplied string. If the argument file=true is given, the entire log file will be returned (not only the part that is kept in memory by the node).
|
/grid/node/JVMID/log /grid/node/JVMID/log?filter=ERROR /grid/node/JVMID/log?file=true |
| stop | POST | Stops the specified node (JVMID). It is possible to specify a grace period before the node is forcefully stopped. A grace of -1 means that it is up to the grid to decide on the grace period. The reason that is given for the stop is logged in the node log before the node is stopped | /grid/node/JVMID/stop?graceSeconds=-1&reason=reasonDescription&block=true |
| offline | POST | Puts a node (JVMID) in an offline sate. | /grid/node/JVMID/offline |
| online | POST | Puts a node (JVMID) in an online state. | /grid/node/JVMID/online |
| nodeWeight | GET | Returns the node weight of a node (JVMID). | /grid/node/JVMID/nodeWeight |
| nodeWeight | POST | Sets the node weight of a node (JVMID). | /grid/node/JVMID/nodeWeight?weight=100 |
| resetLogCounters | POST | Resets the log counters for a node (JVMID). | /grid/node/JVMID/resetLogCounters |
| status | GET | Returns status information for a node (JVMID). The returned status contains such things as log warning and error counts, memory usage, CPU usage, and offline state. | /grid/node/JVMID/status |
Configuration-related REST Services
| Resource | Type | Description | Sample Path |
|---|---|---|---|
| config/binding/update | GET |
Updates a binding in a grid. The binding name is required. Specifying a host is optional. You can also list multiple hosts and you can indicate all hosts with an asterisk (*). The initial, max, and min provide values for the initial binding count, maximum binding count, and minimum binding count. It is also possible to set maximum hosts (not implemented), global or per host context, balancing type and preferred host; for more information, see Edit Application. |
/grid/config/binding/update?name=binding_Name&host=host_Name [&host=host_Name...]&initial=initial_value&max= max_value&min=min_value&maxHosts=3&isGlobal=true&balancingType=Standard&preferredHost=hostName |
| config/host/add | GET |
Adds a host. The fully qualified domain name is required. The host name is optional. If you do not supply it, it will be derived from the FQDN. The agent port is optional. If you do not supply it, the primary host agent port is used. If you supply a port, you must ensure it is free. No validation is done. The optional active value indicates the initial state of the host when deployment is complete. Valid values are true and false. The optional failover value indicates whether this host should provide failover capabilities for the registry. If you do not set this, it will be set to true if there is no existing registry failover host. Valid values are true and false. |
/grid/config/host/add?fqdn=FQDN&port=agentPort&host= host_Name&active=active_value& failover=failover_value |
| config/host/remove | GET | Removes a host. The host name is required. | /grid/config/host/remove?host=host_Name |
| config/host/update | GET | Activates/deactivates a host. The host name and the active value are required. Valid values for the active value are true and false. | /grid/config/host/update?host= host_Name&active=active_value |
| config/host/installer | GET |
Downloads the installer jar file. The host name is required. It is the name of the host you want to download the bootstrap jar for. |
/grid/config/host/installer?host=host_Name |
| config/refresh | POST | Force a refresh of the Grid configuration. | /grid/config/refresh |
| config/deploy/appName | POST | Deploy an application from the application repository onto an additional host (scale-out). | /grid/config/deploy/appName?repoAppId=repositoryApplicationID&host=hostName |
Certificate Signing REST Services
| Resource | Type | Description | Sample path |
|---|---|---|---|
| gridca/csr | POST |
REST service used to submit a Certificate signing Request to the Grid Certificate Authority. This REST service is session annotated to the grid-admin role only. The main use is to automatically issue host and SSL certificates during initial installation of a grid host. The response is a CertificateAuthorityResponse object that includes a status and a ticket ID. The ticket ID is used to query the checkPendingCertificate REST service for an issued certificate. If the csr is omitted in the request the response status is set to "failed". The csr must be submitted as a PEM encoded string of a PKCS#10 certificate signing request. |
gridca/csr with csr=the PEM encoded PKCS#10 request as the post data. |
| gridca/pending/{ticketid} | GET | Check the status of a signing request. If the ticketid is invalid a failure message is delivered in the CertificateAuthorityResponse object. If the ticketid is valid and the certificate has been issued, the certificate is provided in the CertificateAuthorityResponse object as a PKCS#7 string in the message. The ticketid is a String which represents the request ID of a signing request. | gridca/pending/TICKETID |
| gridca/symkey/{ticketid} | GET | Method used to get a symetric property encryption key for a host after having requested a host certificate for signing. The method checks the status of a signing request. If the ticketid is invalid an failure message is delivered in the CertificateAuthorityResponse object. If the ticketid is valid and the certificate has been issued, the symetric key of the host is provided in the CertificateAuthorityResponse object as a PKCS#7 string in the message. The ticketid is a String which represents the request ID of a signing request. | gridca/symkey/TICKETID |
| gridca/revoked/{sn} | POST | Method used to ask the Grid Certificate Authority if a specific certificate has been revoked. If an invalid serial number is provided the CertificateAuthorityResponse has status failed. If a valid serial number was provided and the certificate has been revoked the response message is "revoked". For all other scenarios is the response message "good". | gridca/revoked with sn=SerialNumber as post data where SerialNumber is the String representation of the certificate serial number. |
| gridca/clientcsr | POST | REST service used to submit a Certificate signing Request for a Client Certificate to the Grid Certificate Authority. There is no session annotation or role restrictions on this REST service. The client certificate requests are not automatically issued. A Grid CA administrator must first review the requested grid roles, approve of them and manually issue the certificate. The response is a CertificateAuthorityResponse object that includes a status and a ticket ID. The ticket ID is used to query the checkPendingCertificate REST service for an issued certificate. If the csr is omitted in the request the response status is set to "failed". The csr must be submitted as a PEM encoded string of a PKCS#10 certificate signing request. | gridca/clientcsr with csr=the PEM encoded PKCS#10 request as the post data. |