JSON Over xWeb Overview

To create a new API call in POSTMAN:

1. Use the GET and POST examples described in the xWeb Methods topics to set up the correct endpoint URL.

2. Make sure the Authorization is set to Basic Auth.

   1. In iWeb, go to Admin > Users

   2. Select a user or create a new one.

   3. Set the password in the xWeb Settings section.

   4. In POSTMAN, use the iWeb "User Code" and the xWeb password as the credentials.

3. For POST calls, click the "Body" tab for the request.

4. Select the "raw" data option.

5. In the content type dropdown, select "JSON".

6. Enter the POST data in JSON format.

7. Click "Send" when ready to test.

 

Tokens

1. All xWeb REST requests require either a username/password with BASIC auth, OR BEARER auth with a token.

2. Depending on the settings, tokens may be reused or may be good for a single use.

 

Note: An xWeb authentication token is returned with all JSON over xWeb calls. The token is in the WWW-Authenticate header.

To view the authentication token in POSTMAN:

1. Complete an API call.

2. In the response section, click "Headers".

3. Locate the WWW-Authenticate header.

4. The value will look like: "Bearer token = eb5667ab-25ac-45c9-b831-23b43be8f194"

5. The Guid value can be used in baseline xWeb calls.

 

Note about the xWeb/JSON API endpoint

1. This xWeb/JSON endpoint encapsulates all xWeb API methods.

2. Request and Response bodies are in JSON instead of SOAP XML.

3. For xWeb methods with either no parameters or only simple parameter types (no objects, no arrays), either GET or POST requests can be used.

4. For xWeb methods with complex parameter types (objects, arrays), only POST requests can be used.

5. The URL path for both GET and POST requests is xWeb\JSON\<method name>.

• For example: https:\\mySite\xWeb\JSON\Authenticate.

6. For POST requests, the request body JSON contains the method name and parameters.

   • Note that the method name appears both in the URL and in the request body.

   • You must include all parameters in the request body, even if their value is empty.

   • See the specific documentation of the xWeb method you are calling for the correct formatting of the request body.

7. For GET requests, the parameters are passed in the URL query string.

   • Make sure that the parameter values are URL encoded.

   • If the method requires any object or array parameters, a GET request will not work, you must use a POST request to call it.

   • You must include all parameters in the query string, even if their value is empty.

8. JSON over xWeb includes the “Status” method (e.g. https:\\mySite\xWeb\JSON\Status) function which not available in SOAP-based xWeb calls.

   • The Status method can only be called with a GET request

   • It returns the xWeb version number and current time stamp (in UTC - Coordinated Universal Time ).

   • It does not require authentication.

 

Caution! Pay close attention to the URL in the POST/GET to ensure you are testing against the correct site.

 

SOAPUI is the recommended testing tool for XWEB API endpoing testing.

To start using SOAP UI

1. Create a new SOAP project.

2. Set the Initial WSDL to:

https://{root_domain}/xweb/secure/netforumxml.asmx?wsdl

3. Wait for the xWeb methods to populate. This will take a while.

 

Cloning new request:

1) Each method call, when expanded, has a sample "Request".

2) Right click on a request, and click "Clone".

3) Give the request a new name.

 

Note that each NetForum environment has the same WSDL definition. When testing requests against

multiple environments - such as TEST and PROD - simply clone a request, give it a description name,

then update the URL to the new environment. So you can have a "TEST Request" and "PROD Request" under

a method name.

 

Caution! Pay close attention to the URL in the top of the request window as you can easily test against the wrong environment.

 

Get an authentication token:

1. Locate the "Authenticate" method in the WSDL list.

2. Clone the default request into a new one.

3. Enter your credentials.

   1. In iWeb, go to Admin > Users

   2. Select a user or create a new one.

   3. Set the password in the xWeb Settings section.

   4. In SoapUI, use the iWeb "User Code" and the xWeb password as the credentials.

4. Send the request.

5. In the response window, the token value is in the "token" node of the SOAP header.

f9307fd7-f70b-4424-b863-30d5830fa171

 

Using a token in a request:

1. All xWeb SOAP requests require a token.

2. Depending on the settings, tokens may be reused or may be good for a single use.

3. Each new response has a new token in the token header of the SOAP response.

4. Put the token in the node in the header of each request.

5. If a token has expired, you will receive a "InvalidTokenException" SOAP response with a message of "Failed".

 

Important! UNLESS NOTED, EVERY API REQUEST REQUIRES EITHER BASIC AUTH OR BEARER AUTH HEADERS.