Information Classification: External Restricted.
See https://www.chili-publish.com/security
SOAP to REST
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:
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:
<GenerateApiKey xmlns="http://www.chili-publisher.com/"><environmentNameOrURL>ft-nostress</environmentNameOrURL><userName>myuser</userName><password>password</password></GenerateApiKey>
Of course because of SOAP, we need to wrap the body around some ceremony, so the actual request would look like:
<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>
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><apiKey succeeded="true" key="T171mmpis6yzUOCOg_rc1bc1vstFsPz6v29pGonj0fwHgeiMw6GvqVNB7ep7gf+NgjT5+0kPfQX7XQU2ujAipl5orcwgl7bm" validTill="2020-10-23 15:07:40Z" superAdmin="false" /></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.
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.
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.
Request Element | XML | JSON |
---|---|---|
Body | <?xml version="1.0"?><GenerateApiKeyBodyWrapper><userName>myuser</userName><password>password</password></GenerateApiKeyBodyWrapper> | { |
Header | Content-Type: application/xml | Content-Type: application/json |
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.
All information on this page must be treated as External Restricted, or more strict. https://www.chili-publish.com/security