application connector operations

proiv dashboard

Trail: PROIV Documentation > Application Connector > Application Connector Operations

RESTful Web Services Demo

The demo uses the Restful Web Service definition PROIV Demo Service and makes call to an example PROIV media database.

To make calls to the web service select the restful method and click the Send button.

RESTful Web Services Demo Configuration

To set the RESTful Web Services Demo configuration, do the following:

1. On the Application Connector Operations page, expand RESTful Web Services Demo.
   The Application Connector operations page appears.

2. Enter the configuration as required. The following table describes the fields that can be configured.

   Field Name	Description
   Options
   Authorization
   Security id	Enter the security id. Setting the security id enables HTTP access security on the service. The server sends the text to the client requesting the service, and the client needs to respond with the security secret specified in the next field.
   Secret	Enter the secret text that the HTTP client needs to respond with if there is a security id. If there is no security id, this field is ignored.
   CORS
   Enable CORS	Cross-origin resource sharing (CORS) defines a way for client web applications that are loaded in one domain to interact with resources in a different domain. CORS (Cross-Origin Resource Sharing) Abbreviation for Cross-Origin Resource Sharing. This is a mechanism that allows a restricted resource on a web page to be requested from another domain outside the domain from which the resource originated. The CORS field also holds the comma separated list of origins that are acceptable to the service. If you want to accept requests with no origin, then the CORS field must be empty (that is, CORS is turned off). The CORS field holds a list of origins and if the field contains at least one origin (* is counted as an origin) then the request must contain an ‘Origin’ header that matches one of the origins in the field. If it does not, then the request will be rejected with an error status (403 – Forbidden). An origin can be either a protocol/host/port triple or a GUID (Globally Unique Identifier). If the origin is triple (most likely) then it can be defined in the CORS field as a full triple, without the protocol or without the port. The host must always be fully defined and no wild cards are allowed in the host name. An origin defined in the CORS field without a protocol will use whatever protocols are defined for the service. Note: A PROIV Restful service only supports the http or https protocols; so origins defined with other protocols will never match. The protocol defined for a service always overrides any protocol defined in an origin in the CORS field when looking for a match. For example, an origin of ‘http://myhost.com:80’ will never match if the service does not have the http protocol enabled even if the origin supplied in the request is identical. An origin defined in the CORS field without a port will use the default port defined for the service to do a match. For http that is ‘80’ and for https that is ‘443’. It is acceptable to define an origin in the CORS field with just a host name. In this case it will attempt to match request origins using all the protocols defined for the service and the default port defined for the protocol. For more information on CORS, refer to https://www.w3.org/TR/cors/Type your drop-down text here. Turn ON the slider for Enable CORS to enable the service. If this is not set, the service is not available. If you set and save the service it might be auto disabled where a red indicator appears. Click the red indicator to view the message that explains the reason for being auto disabled. Note: If a REST service has both CORS and authorization (security ID & secret) enabled, the CORS Options request must include authorization. If this is not required then authorization for an Options request can be turned off by setting the servlet parameter 'restful_options_needs_authorization' to 'false' in the WebServices web.xml file. By default, CORS is disabled.
   Headers	Enter the request header name for the service to accept; in case of multiple headers, separate the headers with a comma. A request header name defines a name that the service will accept in the request header called 'Access-Control-Request-Headers' for a CORS pre-flight request. The request headers that were accepted will be returned in the response header ‘Access-Control-Allow-Headers’ for the CORS pre-flight request. Request Header Properties The following table consists a list of properties that are available in the RESTfulRequestSSO. Some of these properties are defined by the calling client and may not be present in the RESTful request; hence marked as optional. To access these properties, use the getHdrParameter method on the RESTfulRequestSSO. Parameter Name Description Accept (optional) String that represents content type, expressed as MIME type, that the client is able to understand. Accept-Encoding (optional) String that represents content encoding, usually a compression algorithm, the client is able to understand. Cookie (optional) String that contains stored HTTP cookies previously sent by the server with the Set-Cookie header. Note: The RestfulRequestSSO makes the cookies available through the getCookie method. Host (optional) String that specifies the domain name of the server (for virtual hosting), and (optionally) the TCP port number on which the server is listening. User-Agent Contains a characteristic string that allows the network protocol peers to identify the application type, operating system, software vendor or software version of the requesting software user agent. cookies Signifies as a SDO (Structured Data Object) that is an array of the cookies in the Cookie header. Each element in the array is an SDO with a ‘path’ string (the name of the cookie) and a ‘value‘ string. Note: This array may be empty if there are no cookies. To get a reference to this object you will need to use the getObject method with a path of ‘header/cookies’ as the getHdrParameter method will return the JSON string of the object. mappedString This string is a part of the calling URL that was identified as identifying the Restful Service that called the Restful task being executed. This will be the Path property in the Restful Service definition. method String that represents a HTTP request method, value can be one of GET, PUT, POST or DELETE. protocol This string is the HTTP request protocol; can be either HTTP or HTTPS. referrer (optional) This string contains the address of the previous web page from which a link to the currently requested page was followed; it can be an empty string. url This string is the full URL used to access this RESTful Service. urlPath This string is the part of the URL following the host port. A service does not need to use any headers, hence the field can be left blank but if a CORS pre-flight request does specify headers in the ‘Access-Control-Request-Headers’ header, then these must be defined in this field or an error status will be returned as stated in the Failed Status Responses. Failed Status Responses The PROIV REST server will respond with a failed status code to any request that does not pass the CORS processing. These status code are defined below: 406 Not Accepted – This status code is returned if a CORS pre-flight request is received when CORS processing for the service is not turned on (that is the ‘CORS’ field in the service definition is empty). 403 Forbidden – This status code is returned for a number of CORS failures: • There is no ‘Origin’ header in a CORS pre-flight or simple request. • The origin specified in the ‘Origin’ header, in a CORS pre-flight or simple request, did not match any origin specified in the service definition ‘CORS’ field using the rules defined above. • There is no ‘Access-Control-Allow-Methods’ header in a CORS pre-flight request. 405 Method Not Allowed – The method specified in the ‘Access-Control-Allow-Methods’ header, in a CORS pre-flight request, is not one specified in the service definition. 417 Expectation Failed – One of the headers specified in the ‘Access-Control-Request-Headers’ header, in a CORS pre-flight request, was not defined in the ‘Req Headers’ field in the service definition. A response with a failed status code will also contain a ‘RWS_Error’ header that holds a string with a short explanation of the reason for failure. Note: The ‘Authorization’ header used by the PROIV REST server is automatically included in the list of acceptable request headers so does not need to be defined here.
   Asynchronous
   Asynchronous	Turn ON the slider for Asynchronous to execute the REST service asynchronously. Asynchronous RESTful Web Service The request processing in PROIV works by default in a synchronous processing mode, which means when you invoke a web service, the invoking client application waits for the response to return before it can continue with its work. This model is typically sufficient for processing of requests for which the processing resource method execution takes a relatively short time. However, in cases where a service execution is known to take a long time to compute the result, server-side asynchronous processing model may be used. This helps the client application to continue its work and handle the response later on. In the Asynchronous model, the association between a service request processing thread and the PROIV kernel task is broken. Asynchronous REST services will start a new thread to access the PROIV Kernel and return a 202 (Accepted) response status immediately. The PROIV kernel processing thread continues in the same way as it does for synchronous REST services. To identify an Asynchronous REST service, the REST server looks for the request header property called ‘Operation-Type’ and if it has the value of ‘async’ then the service will be processed asynchronously. Any other values will cause the service to be processed synchronously. If the header is not present, then the service will be processed synchronously. After an Asynchronous service has started, the client can poll the server sending requests to ask for the status of the service. The returned response status will be 200 (OK) and the data status will be ‘In Progress’ until the service is complete. When the service is complete the returned response status will be 303 and the response header will contain a URL that will return the service result. There is no change in the definition of a PROIV REST service in order to run a service asynchronously. All currently defined REST services can be run synchronously or asynchronously. The following section diagrams describes the flow of synchronous and asynchronous REST calls: Process flow for Synchronous REST web service request Process flow for Asynchronous REST web service requestType your drop-down text here.
   HTTP Request Method
   Method	Select a method. Refer to RESTful Web Service methods for more information. By default, GET method is selected.
   Request Data
   artist	Represents an artist name as a field in the media database.
   title	Represents the title of the artist in the media database.
   URL
   Endpoint	The URL is created automatically with the specified artist and title values. The URL is recognized by the server as a request for a RESTful Service. This can be any text but must start with "/". If you do not put "/" at the beginning, the "/" gets added automatically when the service is saved. Click Send to execute the REST call.
   Response
   Status	The path is the last part of a URL that will be recognized by the server as a request for a RESTful Service. This can be any text but must start with "/". If you do not put "/" at the beginning, the "/" gets added automatically when the service is saved.
   Response Body	A service method may define the acceptable responses for a service call. You can create as many responses as you want and you do not have to define any responses. You can define the body data for a service method which requires request body data when it is called. Only methods of type ‘post’ or ‘put’ can define a request body. This body field defines a JSON schema for the request body content and this schema will be used by the test panel and the client generation tool to provide some checking that the request body has the correct structure before a call to the service is performed. To help in schema generation you can enter an actual JSON object and click ‘{o}->{s}’ on the right of the field and it will convert your JSON object to a valid JSON schema.

RESTful Web Services Test

To test the RESTful Web Services Demo configuration, do the following:

1. On the Application Connector Operations page, expand RESTful Web Services Test.
   The PROIV Demo Service section appears.

   Field Name	Description
   Use secure protocol	Turn ON the slider to use secure protocol (HTTPS). If the slider is turned OFF, the service will use HTTP protocol.
   POST	Enter the values for the fields such as title, address, value, artist and format. Click Test to test the service with the configured values. The response is displayed under the Response section with the response code and description as you have set in the POST method of RESTful Web Service configuration.
   GET	Enter the values for the fields such as artist and title. Click Test to test the service with the configured values. The response is displayed under the Response section with the response code and description as you have set in the GET method of RESTful Web Service configuration.
   DELETE	Enter the values for the fields such as artist and title. Click Test to test the service with the configured values. The response is displayed under the Response section with the response code and description as you have set in the DELETE method of RESTful Web Service configuration.
   PUT	Enter the values for the fields such as title, address, value, artist and format. Click Test to test the service with the configured values. The response is displayed under the Response section with the response code and description as you have set in the PUT method of RESTful Web Service configuration.

2. Set the configuration as required. The following table describes the fields that can be configured.

SOAP WSDL

To set the SOAP Web Services Demo configuration, do the following:

1. On the Application Connector Operations page, expand SOAP WSDL.
   The SOAP services that are configured are displayed. The Demo Web Service appears by default.

2. The following table describes the fields that helps use the service for the selected web service.

   Field Name	Description
   Use secure protocol	Turn ON the slider to use secure protocol (HTTPS). If the slider is turned OFF, the service will use HTTP protocol.
   Endpoint	The URL is created with the specified configuration settings. You can not change the URL as it s read-only. The URL is recognized by the server as a request for a SOAP Service. This can be any text but must start with "/". If you do not put "/" at the beginning, the "/" gets added automatically when the service is saved.
   WSDL The Web Services Description Language (WSDL) is a standard XML string that defines the functions available in a web service.	Enter WSDL URL to get a web page. You can use the URL to see the XML that is generated for the web service when executed by a service client. Note: The WSDL URL can be used by an external web services client to collect the WSDL and execute the services.

Related Topics

Dashboard Overview

Comment on this topic

Topic ID: 830005