SOAP to REST

Authored by Sean Crowe, Niels Grootvriendt

• 4 months ago

• Updated

Why The Change

Version 5.6 introduced a new way of integrating with CHILI Publisher via our REST API. The switch to REST was done in a quest for increasing performance, shrinking request overhead, and allowing ease of versioning for backward compatibility.

With this new API, we introduced Swagger, and Open API compatible endpoint documentation. This interactive documentation allows easy API testing, generating clients, and importing the REST API into API testing tools such as Postman. This will boost productivity and reduce time to market for all integrations.

Internally the Editor and BackOffice exclusively using the REST API.

Swagger Documentation

As mentioned above, with REST we've also added an interactive documentation portal. This can be found by adding /swagger/docs/ui/ index to your CHILI endpoint.

For example, the Customer Success environment is

We can access the interactive documentation portal by changing our URL to:

Of if we just want the JSON documentation for client generation:

Swagger will allow you to explore the REST endpoints, see some documentation on them, and try them out without the need for writing any code. You can learn more about using swagger from the following articles:

• Basic Guide to Using Swagger

• Generating a REST Client With Swagger

To make the conversion from SOAP to REST easier, we have named all the endpoint summaries with their SOAP equivalent. Ignoring ceremony, we have kept the responses the same, so you would not have to change the parsing of the responses. Making it a quick and easy transition.

What Is The Difference

SOAP relies exclusively on XML to provide messaging services. Microsoft originally developed SOAP to take the place of older technologies that relied on binary messaging. However, SOAP contains a lot of ceremony. Each SOAP request must include an envelope, a body, and a value type for each parameter. This ceremony increases both request and response size, while not following modern web standards.

Our REST API provides a lighter-weight alternative that relies on simple URL endpoints using HTTP verbs (GET, POST, PUT, and DELETE) to perform tasks.

More specifically, switching from SOAP to rest requires you d understand the four main differences:

• Endpoints differ for each function

• Endpoints use different HTTP verbs

• Some parameters are now in the endpoint URL as part of the path or the

• The API key is now required to be passed in the header instead of in the body of the response

  • The header is named API-KEY

Switching from SOAP to REST

As seen from the differences above, there are many differences between REST and SOAP. This is not surprising as the REST style of APIs is a completely different format than SOAP. Therefore, the switch to REST will require a complete rewrite of your functions that make requests.

If you were using an autogenerated client, such as provided by Visual Studio, you will need to create your own client or modify one created by Swagger or Postman. At the current moment, there is no way to generate a plug-n-play client.

The good news is that for responses, ignoring ceremony, the body of a response is the same. Because the responses are the same, very little tweaks need to be done to handle the reactive part of your code.

Below you will find the example of using the GenerateApiKey function both with SOAP and REST. While this example is useful, the Swagger interactive documentation will provide the best resource for using the new REST API.

SOAP to REST Example

SOAP GenerateApiKey

So for SOAP our request uses the function GenerateApiKey and has the following attributes:

• Verb: POST

  • All SOAP requests will be POST requests

• URL: https://ft-nostress.chili-publish-sandbox.online/main.asmx

  • All SOAP request will use the same endpoint

• Body:

The total request would look like:

curl -X POST https://ft-nostress.chili-publish-sandbox.online/main.asmx -H "Content-Type: application/soap+xml" -d "<?xml version=\"1.0\" encoding=\"utf-8\"?><soap12:Envelope xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns:soap12=\"http://www.w3.org/2003/05/soap-envelope\"><soap12:Body><GenerateApiKey xmlns=\"http://www.chili-publisher.com/\"><environmentNameOrURL>ft-nostress</environmentNameOrURL><userName>myuser</userName><password>password</password></GenerateApiKey></soap12:Body></soap12:Envelope>"

Assuming it is successful, our response will be:

<?xml version="1.0" encoding="utf-8"?><soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"><soap:Body><GenerateApiKeyResponse xmlns="http://www.chili-publisher.com/"><GenerateApiKeyResult>&lt;apiKey succeeded="true" key="T171mmpis6yzUOCOg_rc1bc1vstFsPz6v29pGonj0fwHgeiMw6GvqVNB7ep7gf+NgjT5+0kPfQX7XQU2ujAipl5orcwgl7bm" validTill="2020-10-23 15:07:40Z" superAdmin="false" /&gt;</GenerateApiKeyResult></GenerateApiKeyResponse></soap:Body></soap:Envelope>

Ignoring the ceremony, the actual data we care about in our response XML is everything in the <GenerateApiKeyResult> tags.

<apiKey succeeded="true" key="T171mmpis6yzUOCOg_rc1bc1vstFsPz6v29pGonj0fwHgeiMw6GvqVNB7ep7gf+NgjT5+0kPfQX7XQU2ujAipl5orcwgl7bm" validTill="2020-10-23 15:07:40Z" superAdmin="false" />

From here we can check if our request for the API key was successful and then get our API key for future SOAP calls.

REST GenerateApiKey

So for REST, we need to find the endpoint and the HTTP verb to use. We can find this information in the swagger documentation as all endpoints have a summary with their SOAP function names.

I suggest using the interactive documentation, but for this example, I am going to use the JSON generated documentation.

Simply doing a search over the document for “GenerateApiKey”, you will find the information you need.

Open

As you can see from the picture above, we see a few things:

• Verb: post

  • Each REST endpoint will have a different verb depending on the situation

• Endpoint URL: /rest-api/v1/system/apikey

  • Each REST endpoint will be different

• Parameters: 1 query and 1 body

  • There are three types of parameters you can find:

    • path - means the parameter is in the path of endpoint URL

    • query - means the parameter is a query parameter in the endpoint URL

    • body - means the parameter is part of the body of the request

In this example, I have all the info I need except the body. To find the body, I just need to do another search for the $ref “GenerateApiKeyBodyWrapper”.

From the picture above, you can see that the body takes two properties: username and password.

Open

If you use the interactive documentation, this info will not only be easier to gather but you can test out your REST API endpoint.

Build REST Request

So let us build our request. Unlike SOAP, not all the parameters are in the body. As mentioned above, the environmentNameOrURL is now in the query of the endpoint URL. Therefore we to modify our endpoint from:

to:

The second parameter is the body, which is made up of two parameters: userName and password.

With REST API, we have two choices in building the body. We can use XML or JSON.

Depending on which body type used, we will need to add a header to our request. See the table below to find the body format and the header that is used in that specific scenario.

Brining our request together we get the following:

XML

curl -X POST https://ft-nostress.chili-publish-sandbox.online/rest-api/v1/system/apikey?environmentNameOrURL=ft-nostress --header "Content-Type: application/xml" --header "Accept: application/xml" -d "<?xml version=\"1.0\"?><GenerateApiKeyBodyWrapper><userName>myuser</userName><password>password</password></GenerateApiKeyBodyWrapper>"

JSON

curl -X POST https://ft-nostress.chili-publish-sandbox.online/rest-api/v1/system/apikey?environmentNameOrURL=ft-nostress --header "Content-Type: application/json" --header "Accept: application/json" -d "{\"userName\": \"myuser\", \"password\": \"password\"}"

REST Response

Whether you use XML or JSON, at the current moment your response will be the same XML.

<apiKey succeeded="true" key="T171mmpis6yzUOCOg_rc1bc1vstFsPz6v29pGonj0fwHgeiMw6GvqVNB7ep7gf+NgjT5+0kPfQX7XQU2ujAipl5orcwgl7bm" validTill="2020-10-23 15:07:40Z" superAdmin="false" />

You will notice two things:

• There is no ceremony of the SOAP wrapper that you get with SOAP

• The actual data is exactly the same as the SOAP function, which means that when converting to REST your code can expect and react to the same responses.