SOAP to REST automated documentation

[linabelramirez-]

Hi @Dino / @Anil Sagar @ Google,

I have a question regarding SOAP to REST service transformation.

QA: Is there a way to automate the documentation for the SOAP to REST transformation for the following process without it involving a lot of custom coding?

Automating the following information:

EXAMPLE:

getOrders ->mapped to -> GET /orders

The current state is the following:

1. Front End will send the request as a SOAP Request. (Add Assign Message Policy)

2. APIGEE proxy will convert SOAP request to REST. (Extract Variable Policy)

3. APIGEE will send REST message to Backend. (Assign Message Policy to construct payload in response flow)

[dchiesa1]

Generation of documentation for the REST-to-SOAP transform can be automated , IF your REST resources conform to a relatively stable pattern.

Often we use the term "SOAP-to-REST" to refer to building a REST facade on an existing SOAP service. SOAP, as you know, doesn't have a strong opinion about how to model resources, and how to model actions on resources. As a result you can have SOAP operations like placeOrder, inquireOpenOrders, queryCustomerId, and so on, and various representations of resources for each operation. Converting from SOAP to REST (in the common direction) is therefore a choose-your-own-adventure endeavor. There will be decisions to be made about how to do the conversion in the most appealing manor.

REST, on the other hand, has an opinion about how resources and actions ought to be modeled. Therefore converting a REST service into a SOAP service ought to be automatable; it ought to require no decisions at all. Just application of patterns. For a GET, call the operation getResource. For a POST, call the SOAP operation createResource, and so on.

regarding using the ExtractVariables policy and AssignMessage to construct SOAP payloads - I guess you mean on the RESPONSE flow, right?

If the client is a SOAP client, and the backend (upstream) service is a REST service, then for the request, your proxy won't be constructing SOAP payloads. Rather the proxy will de-construct SOAP payloads in the request flow. Maybe unwrap the payload from the SOAP envelope and convert it to JSON.

On the response, the converse.

I think all of this can be automated, if you have a clear description of the REST service, in something like OpenAPI Spec.

[linabelramirez-]

@Dino-at-Google thank you for the context.

Is there a way to automate the documentation for the SOAP-to-REST transformation? Meaning it somehow spits out the transformation documentation, either via logging or via some other form of documentation service api.

Giving us the following infromation:

Ex: getOrders -> mapped to -> GET /orders

Ex: getOrders = GET /orders

Thank you in advance for your help and advice!

[dchiesa1]

Yes, I think it should be easy, if you are using a tool or custom script to programmatically generate the API Proxy.

Just have the tool emit the information you need.

If you are asking if a tool like this exists.... I don;'t know of one.

But I think it would be a relatively simple job to produce one.