RESTful Web Services

This topic provides the general information of PPM RESTful web services.

Overview of PPM RESTful web services

Using the PPM-supported REST APIs, developers can retrieve and perform CRUD (create, read, update, delete) operations on the related entities.

For the REST APIs whose URIs are prefixed with http(s)://server:port/itg/rest2/, see Interactive REST API Help.
For the REST APIs whose URIs are prefixed with http(s)://server:port/itg/rest/, see the following:

The Web Application Description Language (WADL) descriptor that lists all supported PPM RESTful Web services can be found at the following location:
http(s)://server:port/itg/rest/service.

Configuration

To enable RESTful web services, make sure the following line is in the websecurity.conf file:

/rest=com.kintana.core.web.servlet.AllAccessURLSecurity

If not, copy and paste it to the websecurity.conf file, which is located in the <PPM_Home>/conf directory.

Authentication

All requests to the RESTful Web services interfaces (URLs) must be authenticated. PPM supports the following authentication types for RESTful Web services:

Authentication	Description
HTTP Basic Access Authentication	When you use the HTTP Basic Access Authentication, an authorization HTTP header is sent along with the request, containing the base64-encoded username and password. For example: `Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==` For more information about HTTP Basic Access Authentication, see RFC 2617.
HTTP Request Query String	When you use the HTTP Request Query String, you must specify the username and password parameters in the URL. For example: `http://<instance_address>:<port>/itg/rest/dm /requestTypes?username=admin&password=admin`
Lightweight Single Sign-on (LWSSO)	For details, see the Installation and Administration Guide.
JSON Web Token (JWT)	Only the RS256 algorithm is supported for signing JWT, which requires you to define a JWK provider. The HA256 algorithm is not supported. When you use the JWT, you should specify values for the following parameters: JWT_JWK_PROVIDER_URL. Required parameter. Defines the URL of the JWK provider. The `/.well-known/jwks.json` part should be omitted. If no value is provided, the JWT authentication is not activated. JWT_JWK_PROVIDER_PROXY. Optional. Must use the format `host:port`. JWT_USER_INFO_CLAIM. Specifies the JWT claim in which the PPM username or logon ID will be stored. If empty, defaults to `sub`.
API key authentication	Obtain a secret key from PPM administrator and enter it in the following URL to authenticate: `https://<instance_address>:<port>/itg/api-auth?username=<XYZ>&key=<ABC>` For details about how to obtain a secret key, see Set up API key access. Upon successful authentication, the CSRF-X-TOKEN token is returned. If required, provide this token in the subsequent API calls.
Bearer authentication	Bearer authentication uses security tokens called bearer tokens for authentication. When enabled, PPM API keys can be used as bearer tokens to grant access to their holder. For details about enabling API keys as bearer tokens, see Enable API keys as bearer tokens. Obtain an API key from your administrator and pass it as a bearer token in the following authorization header to authenticate: `Authorization: Bearer <API_KEY>` Note: The API key must be enabled as bearer token. Bearer tokens can only be used to make REST API calls to `http(s)://server:port/itg/rest2/` REST API sessions using bearer authentication automatically close once the REST calls complete, even when configured with `ephemeral: false` in the header. You must include the API key in the authorization header for each REST call. To maintain a long session for subsequent calls, use API key authentication.

Caution:

HTTPS is preferred whenever you use RESTful Web services by Basic Access Authentication or Request Query String authentication in order to prevent username and password to be transmitted over the network.
Since Request Query String authentication requires your username and password as the parameters in the URL, your username and password will be logged in the log file if the web server is configured to log URLs. This will cause a security flaw.

Session management

If you make multiple REST calls to PPM and only pass the basic authentication information, a new PPM session is created every time and the session is closed until it times out.

We recommend that you use either of the following to manage the REST session:

Keep track of the REST session once it is opened by retrieving the session cookie in the response, and re-submit it in subsequent calls to reuse the session instead of opening a new one. Once you do not need the session anymore, close it by calling GET /itg/rest2/logout.
Pass the following header in every REST call:

Ephemeral: true

This automatically closes the session once the REST call completes. This is useful if you want to make many individual REST calls without any easy way to reuse opened sessions.

Messaging type

PPM supports the following two messaging types for RESTful Web services:

XML (default)
JSON

To enable JSON messaging type, you have to append the string alt=application/json to the parameter list of the URL.

For example:

http://<instance_address>:<port>/itg/rest/dm
/requestTypes?username=admin&password=admin&alt=application/json