Important Considerations when Configuring Virtual REST Services

With Web REST Services, the Native REST Service endpoint that is sent by CentraSite to API Gateway inside a Virtual REST Service definition is a static element. Once the Virtual REST Service is successfully deployed to API Gateway, the real endpoint is returned to CentraSite as part of the response message during deployment. At run time, when a SOAP request is received, that request is POSTed to the endpoint that is statically defined in the Virtual REST Service definition.

However, with REST Services or XML REST Services, the endpoint is flexible. The REST Services or XML REST Services describe data as resources. The resources are accessible through logical endpoints that have application meaning to users. For example, a collection of textbooks might be defined as a resource with the following URL:

A specific book with an identifier of 1234 would be accessible with the following URL:

Due to this difference and others, you should keep the following topics described in this chapter in mind when you configure a REST Virtual REST Service.

When you configure a Virtual REST Service, you specify the Native REST Service name, an endpoint, and the HTTP method type(s) that are included in the message (GET, POST, PUT, PATCH, DELETE). From this information, CentraSite generates a Virtual REST Service definition that includes REST Service and operation elements, as well as an endpoint and binding element pair for each HTTP method specified.

CentraSite generates an operation name to be included when the Virtual REST Service definition deployment message is sent to API Gateway. This means that if you create a Virtual REST Service called VS1, and you specify a Native endpoint, then the endpoint exposed by API Gateway for calling the Virtual REST Service will be /ws/VS1/Invoke.

For example, assume the following endpoints are deployed:

Assume that the example Virtual REST Service is deployed with two HTTP method bindings: GET and POST. Both of these bindings have operation elements that include the same HTTP location attribute: member. To better illustrate the functionality, the examples below show a series of sample requests from a consumer including the requests' HTTP method. (At run time, REST message detection is dependent upon a consumer using the correct Content-Type when a request is sent.) Each example shows the expected endpoint that API Gateway will send after it has rewritten the endpoint prior to Native REST Service invocation.

Example 1

For a GET, assume that:

The request Content-Type is: application/x-www-form-urlencoded

The endpoint received by API Gateway is: http://localhost:5555/ws/VS1/Invoke

The Native REST Service endpoint sent by API Gateway is: http://localhost:8080/REST Services/mtc/member

The application function is: The Native REST Service returns a collection of members with summary information.

Example 2

For a GET, assume that:

The request Content-Type is: application/x-www-form-urlencoded

The endpoint received by API Gateway is: http://localhost:5555/ws/VS1/Invoke/1234

The Native REST Service endpoint sent by API Gateway is: http://localhost:8080/REST Services/mtc/member/1234

The application function is: The Native REST Service returns summary data for a member with this key.

Example 3

For a GET, assume that:

The request Content-Type is: application/x-www-form-urlencoded

The endpoint received by API Gateway is: http://localhost:5555/ws/VS1/Invoke/1234?detail=true

The Native REST Service endpoint sent by API Gateway is: http://localhost:8080/REST Services/mtc/member/1234?detail=true

The application function is: Query parameters remain intact. Returns a response message with more member details.

Example 4

For a POST, assume that:

The request Content-Type is: application/xml or application/json

The endpoint received by API Gateway is: http://localhost:5555/ws/VS1/Invoke/1234

The Native REST Service endpoint sent by API Gateway is: http://localhost:8080/REST Services/mtc/member/1234

The application function is: The request message provides the contents needed to create the member resource.

Example 5

For a GET, assume that:

The request Content-Type is: application/x-www-form-urlencoded

The endpoint received by API Gateway is: http://localhost:5555/ws/VS1/Invoke/joe

The Native REST Service endpoint sent by API Gateway is: http://localhost:8080/REST Services/mtc/member/joe

The application function is: Fetches the member defined with the login joe. (API Gateway contains no metadata in its REST Service deployment to differentiate between the login vs. key GET requests.)

Example 6

For a GET, assume that:

The request Content-Type is: application/x-www-form-urlencoded

The endpoint received by API Gateway is: http://localhost:5555/ws/VS1/Invoke?type=login&value=joe

The Native REST Service endpoint sent by API Gateway is: http://localhost:8080/REST Services/mtc/member?type=login&value=joe

The application function is: The Native REST Service might also support a static endpoint with constraints defined in query parameters. API Gateway also supports this approach.

When you configure the Entry Protocol step of a Virtual REST Service, it is important to specify all the HTTP methods that are supported for the REST Service. For example, if the Virtual REST Service is deployed to API Gateway and you selected only the GET method in the Virtual REST Service's details page, then API Gateway permits GET invocations. In this case, a POST request will be rejected with a return of statusCode 405 even if the Native REST Service happens to support POSTs.

It is important that the client's requests contain an HTTP Content-Type header. At run time, API Gateway determines which message builder to use based on the message’s HTTP method and its Content-Type. (The absence of the soapAction header will indicate to API Gateway that the message is an XML message.)

The valid HTTP method/Content-Type combinations are as follows:

When configuring a REST Virtual REST Service, you specify whether to route the requests to the Native REST Service with the same HTTP method that is contained in the requests (GET, POST, PUT, PATCH, DELETE), or whether to route the requests with a different HTTP method.

Typically you want to pass each request to the Native REST Service with the same HTTP method that is contained in the request. For example, if a request contains a GET method, you allow the GET method to be passed to the Native REST Service. However, there might be rare cases in which you want to change the HTTP method of a request to different HTTP method. For example, you might want to:

This method...	Can be included in a message of this Content-Type...
POST	application/xml application/json application/x-www-form- urlencoded multipart/form-data or text/xml
PUT	application/xml application/json application/x-www-form- urlencoded multipart/form-data or text/xml
GET	application/x-www-form-urlencoded Note: For Axis Free Mediation Content-Type is not required.
DELETE	application/x-www-form-urlencoded Note: For Axis Free Mediation Content-Type is not required.

When changing this incoming HTTP method...	To...	Note that...
GET	POST	The Content-Type of the changed request is sent as application/xml or application/json, and the charset is UTF-8. Depending on the structure of the Native REST Service, be aware that the Native REST Service might not be expecting the same payload structure that is being sent. In this case, you would need to transform the request message into the format required by the Native REST Service before API Gateway sends the requests to the Native REST Service. For more information, see the Sample XSLT Transformation for GET-to-POST or GET-to-PUT section later in this topic.
GET	PUT	Identical to GET-to-POST, except that API Gateway changes the request's HTTP method from GET to PUT.
GET	DELETE	No comment.
POST	GET	API Gateway will translate the POSTed request elements into query string parameters, in a root element. Note: An incoming POST or PUT request cannot be translated into a GET or DELETE if the request has nested elements. For example: (this is correct) <person> <lastName>Smith</lastName> </person> (this is incorrect) <person> <name> <last>Smith</last> </name> </person> If you want to send additional parameters as part of the request URL, you can transform this payload. To do this, you can use an XSLT file or a webMethods IS REST Service call to add parameters before the request is sent to the Native REST Service.
POST	DELETE	Identical to POST-to-GET, except that API Gateway changes the request's HTTP method from POST to DELETE.
POST	PUT	The Content-Type of the changed request is sent as application/xml or application/json, and the charset is UTF-8.
PUT	GET	Identical to POST-to-GET, except that API Gateway changes the request's HTTP method from PUT to GET.
PUT	POST	The Content-Type of the changed request is sent as application/xml or application/json, and the charset is UTF-8.
PUT	DELETE	Identical to POST-to-DELETE, except that API Gateway changes the request's HTTP method from PUT to DELETE.
DELETE	GET	No comment.
DELETE	POST	Identical to GET-to-POST, except that API Gateway changes the request's HTTP method from DELETE to POST.
DELETE	PUT	Identical to GET-to-PUT, except that API Gateway changes the request's HTTP method from DELETE to PUT.
GET or DELETE	POST or PUT	Note that the query parameters will be picked off the URL and stored as top-level elements when the message is sent to the Native REST Service. The query parameters are ignored on the endpoint URL and lost when we POST to the Native provider (that is, don't change the protocol method).
PATCH	POST or PUT	Note that the query parameters will be picked off the URL and stored as top-level elements when the message is sent to the Native REST Service. The query parameters are ignored on the endpoint URL and lost when we POST to the Native provider (that is, don't change the protocol method).