Karaf CXF REST QuickStart

This quickstart demonstrates how to create a RESTful (JAX-RS) web service using CXF and expose it through the OSGi HTTP Service.

The REST service provides a customer service that supports the following operations

• PUT /customerservice/customers/ - to create or update a customer
• GET /customerservice/customers/{id} - to view a customer with the given id
• DELETE /customerservice/customers/{id} - to delete a customer with the given id
• GET /customerservice/orders/{orderId} - to view an order with the given id
• GET /customerservice/orders/{orderId}/products/{productId} - to view a specific product on an order with the given id

When the application is deployed, you can access the REST service using a web browser.

Building

The example can be built with

mvn clean install

Running the example in fabric8

It is assumed that OpenShift platform is already running. If not you can find details how to Install OpenShift at your site.

The example can be built and deployed using a single goal:

mvn -Pf8-deploy

When the example runs in OpenShift, you can use the OpenShift client tool to inspect the status

To list all the running pods:

oc get pods

Then find the name of the pod that runs this quickstart, and output the logs from the running pods with:

oc logs <name of pod>

You can also use the OpenShift web console to manage the running pods, and view logs and much more.

Access services using a web browser

You can use any browser to perform a HTTP GET. This allows you to very easily test a few of the RESTful services we defined:

Notice: As it depends on your OpenShift setup, the hostname (route) might vary. Verify with oc get routes which hostname is valid for you

Use this URL to display the root of the REST service, which also allows to access the WADL of the service:

http://quickstart-cxf-rest.vagrant.f8/cxf/crm

Use this URL to display the XML representation for customer 123:

http://quickstart-cxf-rest.vagrant.f8/cxf/crm/customerservice/customers/123

You can also access the XML representation for order 223 ...

http://quickstart-cxf-rest.f8/cxf/crm/customerservice/customers/123

Note: if you use Safari, you will only see the text elements but not the XML tags - you can view the entire document with 'View Source'

To run a command-line utility:

You can use a command-line utility, such as cURL or wget, to perform the HTTP requests. We have provided a few files with sample XML representations in src/test/resources, so we will use those for testing our services.

1. Open a command prompt and change directory to cxf-cdi.

2. Run the following curl commands (curl commands may not be available on all platforms):

   • Create a customer

       curl -X POST -T src/test/resources/add_customer.xml -H "Content-Type: text/xml" http://quickstart-cxf-rest.f8/cxf/crm/customerservice/customers
     

   • Retrieve the customer instance with id 123

       curl http://quickstart-cxf-rest.f8/cxf/crm/customerservice/customers/123
     

   • Update the customer instance with id 123

       curl -X PUT -T src/test/resources/update_customer.xml -H "Content-Type: text/xml" http://quickstart-cxf-rest.f8/cxf/crm/customerservice/customers
     

   • Delete the customer instance with id 123

        curl -X DELETE http://quickstart-cxf-rest.f8/cxf/crm/customerservice/customers/123
     

Running the example using OpenShift S2I template

The example can also be built and run using the included S2I template quickstart-template.json.

The application can be run directly by first editing the template file and populating S2I build parameters, including the required parameter GIT_REPO and then executing the command:

oc new-app -f quickstart-template.json

Alternatively the template file can be used to create an OpenShift application template by executing the command:

oc create -f quickstart-template.json

More details

You can find more details about running this quickstart on the website. This also includes instructions how to change the Docker image user and registry.