README.adoc

midPoint custom REST-like overlay

Table of Contents

• Building and running
• Testing
• Technical notes
• Recommendations wrap-up
• Experimental Spring MVC based REST controller

ℹ️	Term "REST" is used as usual in the industry but not in the strict REST meaning. Sorry about that.

Example of a midPoint overlay project that implements a custom REST service. The current version is based on CXF and JAX-RS. Early experimental Spring MVC version is described at the end of this document.

The service is implemented by ExampleRestService class. Two necessary Spring context files are in resources directory.

This project is an adaptation (with some simplifications) of midpoint-custom-service. Head of the master normally follows the current development version of midPoint. See tag v4.4 for the last stable version.

See also README from the basic overlay example, including also midPoint Overlay development notes. Check also related wiki page.

Building and running

Use JDK 11 for building and running this overlay. To build the example run mvn clean package. The final midpoint.jar will be built in target. It can be run directly as executable JAR:

java -jar target/midpoint.jar

The REST service is set up under http://localhost:8080/midpoint/ws/my-ext/rest-example.

Testing

To return user(s) with e-mail address [email protected] try:

• Running cURL command (by default returns XML):

  curl -v --user "administrator:5ecr3t" \
    http://localhost:8080/midpoint/ws/my-ext/rest-example/users/mail/[email protected]

• Running HTTPie command (returns JSON because of -j flag):

  http -jv http://localhost:8080/midpoint/ws/my-ext/rest-example/users/mail/[email protected] \
    -a administrator:5ecr3t

• Alternatively, point a browser to the URL: http://localhost:8080/midpoint/ws/my-ext/rest-example/users/mail/[email protected] and entering administrator name and password. This returns simplified string representation of the value as HTML.

If something doesn’t work as expected, first check that you’re not reusing existing midPoint home directory. If so, delete it, to ensure that the right initial objects are created. You can also set -Dmidpoint.home=…​ on the command line.

Technical notes

ℹ️	Previous to 4.2, CXF servlet was configured directly in midPoint /ws/* mapping. With 4.2 and later this is no longer true and /ws/* is used for REST service (just as /rest and /api). See REST API on our wiki for more.

This overlay sets up CXF servlet on /ws/my-ext/*. If colliding mapping path was chosen (like /ws/*) CXF would completely take over this sub-context. This would break some midPoint internals like node management that uses /ws mapping.

We could map the servlet to /my-ws/* to avoid any collisions as well, but this would be considered default GUI channel. As such, it would not work with basic authentication. If /ws/my-ext/* is used, it does not collide with paths under /ws, neither does it take over /ws completely. At the same time it will be considered REST channel now thanks to /ws/my-ext/* pattern and basic authentication can be used.

SOAP overlay example uses different approach and goes around flexible authentication.

Recommendations wrap-up

• Set up CXF servlet on a unique sub-path under /ws/ (or /api/ or /rest/). This way you will not disrupt existing built-in services and you’ll still get REST channel authentication.

• Alternatively, go for Spring MVC and just add another REST controller. Set up @RequestMapping("/ws/<sub-path>") under any of the paths supporting REST channel, but try not to collide with existing services by choosing distinct sub-path. This will probably be the future of this overlay example as well, for now it’s in an experimental phase.

Experimental Spring MVC based REST controller

With Spring MVC REST already configured for midPoint 4.2 (or later) it is easy to set up new REST controller and operations. However, due to freshness of this approach and minimal testing this part is considered experimental and unsupported.

You can test Spring MVC based REST by:

• Running cURL command (by default returns XML):

  curl -v --user "administrator:5ecr3t" \
    http://localhost:8080/midpoint/ws/my-rest/users/mail/[email protected]

• Running HTTPie command (returns JSON because of -j flag):

  http -jv http://localhost:8080/midpoint/ws/my-rest/users/mail/[email protected] \
    -a administrator:5ecr3t

• Alternatively, point a browser to the URL: http://localhost:8080/midpoint/ws/my-rest/users/mail/[email protected] and entering administrator name and password. This returns simplified string representation of the value as HTML.

Whole implementation is in ExampleRestController. Class extends from AbstractRestController from midPoint to utilize existing common methods. This is convenient but it may change in the future as it is not officially public API.

If this way is used no additional CXF dependency and configuration is necessary. Map controllers under URL patterns using the REST channel, multiple mappings can be used, for examples check ModelRestController.java.