Publish RESTful Web Service Proxy with WADL

This topic discusses how to use RESTful web services with the gateway.
gateway83
This topic discusses how to use RESTful web services with the
CA API Gateway
.
Working with RESTful Web Services
RESTful web services and resource orientation in general provide an alternative approach to exposing web services and web APIs. RESTful web services are an alternative to WS-* style web services built respecting the guidelines and principles or REST (Representational State Transfer). Some of the properties of RESTful web services include:
  •  resources are uniquely identified through the HTTP URI
  •  the action on the resource is dictated by the HTTP verb (method)
  •  resource representations are the HTTP payload
  •  Content-Type not limited to XML; it can be anything else (for example, JSON)
The CA API Gateway can help you secure your RESTful web services to the same extent as WS-* (using SOAP, WSDL) services.
Additional Resources
For more information about REST principles and guidelines see http://en.wikipedia.org/wiki/Representational_State_Transfer
For additional information regarding using the CA API Gateway with RESTful web services, see these resources from CA Technologies:
Securing a RESTful Web Service
The following table summarizes the steps to secure your RESTful web service using the CA API Gateway.
The term "XML application" has a legacy heritage. If your RESTful web service does not use XML, the CA API Gateway can support many other Content-Types.
To...
Do this...
Build a policy to route and validate traffic for an existing RESTful web service
 
STEP 1:
Build a policy in the same manner as a SOAP policy, except use the Publish Web API Wizard instead of the Publish SOAP Web Service Wizard. Be sure to configure the resolution URI pattern to associate the policy with all possible URLs for that service, using the '*' wildcard character. (Reason: Unlike WS-* style web services that have a single URL entry point, RESTful web services refer to the resource ID being acted upon using the URI portion of the HTTP URL. Thus, the URL used is different for each resource, even though the same policy applies. You can specify a different policy for any different URL pattern.)
After publishing, the CA API Gateway becomes the entry point for your RESTful web service. The Gateway reconstructs and proxies to the service endpoint for each incoming request. Responses are similarly reverse-proxied.
For more information, see Publishing a Non-SOAP Application.
 
STEP 2:
The default behaviour of the Route via HTTP(S) assertion is to route to an explicit endpoint URL rather than the entry point URI of the RESTful web service. To replicate the URI downstream, specify it as part of the HTTP routing target using the context variable ${request.http.uri}. For example, specify a target URL as shown below:
http://downstreamServiceHost/something${request.http.uri}
For more information about the ${request.http.uri} variable, see Transport Layer Variables.
If you need to use a specific portion of the URI as part of the policy, you can extract it from the incoming URL (${request.http.url}) using the Evaluate Regular Expression assertion.
 
STEP 3:
You can validate incoming content using any XML-related assertion if your RESTful web services format resources in XML. Examples of such assertions include the Validate XML Schema, Evaluate Request XPath, and Evaluate Response XPath assertions. If your service uses JSON, use the Validate JSON Schema assertion instead.
For any text-based Content-Type, the Evaluate Regular Expression assertion can be used to evaluate specific patterns.
The Threat Protection Assertions may also be useful to help you validate input for your RESTful web service.
Validate HTTP parameters
Specific validation of HTTP parameters can be achieved with the help of the Validate HTML Form Data assertion. This assertion allows you to enforce:
  • which HTTP method is allowed (GET, POST)
  • which HTTP parameters must be present in the request
  • the number of occurrences of each parameter in the request
  • where the parameters occur in the request (in the URL, body, or anywhere within the request)
  • the presence of unnamed fields (allowed/disallowed)
For more information, see Validate HTML Form Data Assertion.
Validate JSON schema
Add the Validate JSON Schema assertion to the policy if you need to validate JSON data structure and property types/values against a JSON schema.
Use the context variable suffix ".mainpart" to access the JSON payload of a specific message (request, response, other). To learn more about this suffix, see "Context Variable Data Types" under "Multivalued Context Variables".
For more information, see Validate JSON Schema Assertion.
Transform between JSON and XML
Use the Apply XSL Transformation assertion to transform from XML to JSON. Use the Set Context Variable assertion and context variables to transform from JSON to XML.
Security options
You can authenticate and authorize requestors using any authentication mechanism appropriate for HTTP. Examples of these include:
  • Require SSL or TLS Transport
  • Require SSL or TLS Transport with Client Authentication
  • Require HTTP Basic Credentials
  • Require Windows Integrated Authentication Credentials
Caching
Cachable resources is a property of RESTful web services. The CA API Gateway offers these assertions to help you implement this aspect of your RESTful web services:
  • Store to Cache
  • Look Up in Cache
Configure the policy
Most assertions can be used for your RESTful web service, but SOAP-specific ones will not be appropriate. The policy validator will warn you.
For more information, see Configuring a Policy.
Restrict HTTP verbs
You can place restrictions on the HTTP methods (verbs) associated with the policy. For example, you can authorize different verbs for different URI patterns. A RESTful web service can use these methods: GET, PUT, POST, DELETE.
To configure the HTTP method that is sent downstream, use the "[Request HTTP Rules] tab" in the Route via HTTP(S) assertion.
You can also branch your policy based on the incoming verb using the context variable ${request.http.method}.
Access HTTP headers
You can access a variety of HTTP header values by using the context variable pattern below:
${<target>.http.header.<name>}
Where "<target>" is either request, response, or a message context variable and "<name>" is the header value being retrieved.
Examples:
  • ${request.http.header.content-type} retrieves the Content-Type from the header (for example, "text/xml")
  • ${request.http.header.date} retrieves the date from the HTTP header
The ${<target>.http.header.<name>} variables are only available for messages that arrive over HTTP, or from the default response to a request that arrived over HTTP. If the latter, the only headers that will be available are the ones destined to be added to the response headers when the response is eventually sent. For more information about this variable, see Transport Layer Variables.