This library provides one option for integrating one web application with the REST API provided by another web application. Typically, a web application that wanted to issue XmlHttpRequests to another web application's REST API would use CORS. The assumption here is that both web applications use compatible single-sign-on technologies so an authenticated user in the first is generally an authenticated user in the second.
But what if the web application hosting the REST API doesn't support CORS? That's where rest-proxy can help.
Without rest-proxy, imagine how you would have to integrate these two applications:
- The application hosting the REST API will likely have separate authentication mechanism, say a "service account" using HTTP Basic/Digest.
- In order for your web application to make REST calls, your application is going to have to have its own REST Controllers which are simply a Proxy for the other application. You'll need a proxy method/controller for every method on the target REST API you want to call.
- Those controllers will be pretty boiler plate, binding the same URL/query pattern that the target endpoint supports, then delegating to some rest client configured with your "service account."
Items number 2 and 3 above are provided with rest-proxy.
- Java 7+
- Spring Framework
- Add the following dependency to your project:
<dependency> <groupId>edu.wisc.my.restproxy</groupId> <artifactId>rest-proxy-core</artifactId> <version>2.0.0</artifactId> </dependency>
- A Spring
@Configurationclass is provided, add
@Import(edu.wisc.my.restproxy.config.RestProxyConfiguration)on one of your existing
@Configurationclasses. If you are using Spring's XML configuration instead, add the following to your
Spring application context:
<mvc:annotation-driven/> <context:component-scan base-package="edu.wisc.my.restproxy"> <context:exclude-filter type="regex" expression="edu.wisc.my.restproxy.config.*"/> </context:component-scan>
- Configure a url-pattern for the Spring DispatcherServlet. If you are writing a My UW App, you may not have the DispatcherServlet already configured. Add the following to web.xml:
<servlet> <servlet-name>proxy</servlet-name> <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class> <load-on-startup>1</load-on-startup> </servlet> <servlet-mapping> <servlet-name>rest-proxy-api</servlet-name> <url-pattern>/proxy/*</url-pattern> </servlet-mapping>
- Now we have to configure the proxy. rest-proxy gets its configuration about the target REST APIs you want to proxy from the Spring
@Environment. If you have a
@PropertySourcealready defined, you can add the necessary properties there, or you can choose to add a separate
@PropertySource(it doesn't matter, they all end up in
@Environmentno matter how many
@PropertySources you have). The most basic configuration available is as follows:
This configuration will result in the url 'http://localhost:8080/proxy/target/foo' (assuming http://localhost:8080 is your web application's address) being a proxy for 'http://somewhere.wisc.edu/something/foo'. If 'http://somewhere.wisc.edu/something' requires service account credentials, the configuration expands to:
target.url=http://somewhere.wisc.edu/something target.username=someuser target.password=somepassword
- Secure your configuration! This is a complicated topic and there is no simple explanation. Some ideas and samples are covered in the reference manual.
Quickstart an example
You need to install gradle 2.x for this to work. Download here: https://services.gradle.org/distributions/gradle-2.14-bin.zip
The rest-proxy-boot module in this project is a Spring Boot project that includes rest-proxy-core. It is intended for demonstration purposes.
- Supply endpoint configuration - you can copy application.properties.example to get started, or add a command-line flag, e.g.
gradle bootRunto start the server
- Verify in your browser
gradle buildto build a standalone jar
- Start the server by running
java -jar rest-proxy-boot/build/libs/rest-proxy-boot-<VERSION>.jar
See docs for more documentation about this project.