Configuration

Friendly URLs can either be based on web service definitions or explicitly configured in FSCOWS@1.1001:WebServiceConfiguration.

Friendly URLs Based on Web Service Definitions

Web Service Definitions

A web service definition defines a set of actions (or SOAP actions), which are bundled in a single accessible endpoint represented by a WSDL. Additionally RESTful services/operations are exposed, too. The list of operations exposed by the web service is defined in FSCOWS@1.1001:webserviceactions.

The format of a friendly URL based on a web service definition looks like:

http(s)://localhost/fsc/MYCOMP_620_1200_WebService.MyOperation

• MYCOMP@620.1200:WebService
  reference of a web service definition
• MyOperation
  a specific web service operation

Note: References in URLs must be written in underscore notation. If the software component reference contains underscores, these are duplicated. The characters “@”, “.” and “:” are substituted by underscores. For example, the reference MY_COMP@620.1200:Web_Service results in MY__COMP_620_1200_Web_Service.

Friendly URL

In case that only the operations defined in a FSCOWS@1.1001:WebServiceDefinition should be exposed for friendly URL access no explicit configuration is necessary, if the following applies:

• The name of the friendly URL is <full reference of web service definition in underscore notation>.<web service operation or short reference of action>.
• The parameters of the actions defined in FSCOWS@1.1001:webserviceactions only contain types that are usable in friendly URLs.
• The parameters of the actions defined in FSCOWS@1.1001:webserviceactions have the same sequence as the parameters of the friendly URLs.
• The actions defined in FSCOWS@1.1001:webserviceactions have zero or one input content.
• The actions defined in FSCOWS@1.1001:webserviceactions have zero or one output content.
• The service supports only HTTP_GET and HTTP_POST (HTTP_POST only if an action defined in FSCOWS@1.1001:webserviceactions has an input content).

Friendly URLs Configured in FSCOWS@1.1001:WebServiceConfiguration

Friendly URLs can be explicitly configured in the FSCOWS@1.1001:WebServiceConfiguration.

Following parameters can be defined:

• Type
  The type determines how parameters of the REST call are mapped to the implementation.
• URL Marker
  The primary part of the friendly URL.
• URL Arguments (Necessary Type: OpenAPI)
  Contains static URL parts, named URL parameters and named query parameters.
  For example: /{arg1}?{urlarg1}
  Match URL: http://localhost/fsc/documentapi/123?urlarg1=true
  Defines the URL parameter arg1 and the query parameter urlarg1.
  For example: /v2/{arg1}/{arg2}?{urlarg1}{urlarg2}
  Match URL: http://localhost/fsc/documentapi/v2/123/456?urlarg1=true&urlarg2=FK7
  Defines the URL parameters arg1 and arg2 and the query parameters urlarg1 and urlarg2.
  Match URLs 
  Request URLs are matched using
  1. FSCOWS@1.1001:friendlyurlurl
  2. FSCOWS@1.1001:friendlyurlallowedmethods
  3. FSCOWS@1.1001:friendlyurlargs static URL parts
  If multiple static prefixes match, the entry with the most matching static url parts is used.
  FSCOWS@1.1001:friendlyurlallowedmethods
  The request method has to match the specified methods.
  FSCOWS@1.1001:friendlyurlaction: new window
  The arguments for the action are matched by name.
  FSCOWS@1.1001:friendlyurloutcont: new window
  If set, the value of this parameter is used as response content.
  Input Parameters 
  Input parameters are resolved by name from: 
  1. Named URL parameters
  2. Named query parameters
  3. Request content 
  JSON (Content-Type: "application/json; charset=utf-8") 
  The document is parsed and named parameters are resolved by name based on parameter types.
  Basic JSON Types: The value is matched according to FSCEXPEXT@1.1001:JSON2Value.
  COOSYSTEM@1.1:DATETIME: The value is matched according to xs:DateTime eg. "2001-10-26T21:32:52".
  FSCOWS@1.1001:NamedPart: The string value has to match the filename of an attached document.
  Other aggregate type: The value is expected to be structured. Every structure member is resolved as described.
  Values must match the corresponding type, enumeration values are matched by reference.
  Output Parameters 
  Output parameters are added by name and to a result JSON document "Content-Type" "application/json; charset=utf-8".
  The transformation of values is implemented according to the resolving of input parameters.
• DAV Action
  The action to be executed.
• Content Input Parameter
  Contains the HTTP body of the HTTP request. If present, the content is passed to the DAV action for processing. The parameter is passed as a type COOSYSTEM@1.1:CONTENT.
• Content Output Parameter
  If the DAV action returns one or more contents as result, this parameter is used to define which content is used as HTTP body of the HTTP response. The parameter must be of type COOSYSTEM@1.1:STRING, COOSYSTEM@1.1:CONTENT, COOSYSTEM@1.1:CONTENTLIST or COOSYSTEM@1.1:Content. In the latter case, the value in the contained attribute COOSYSTEM@1.1:contextension is used to determine the MIME type of the outgoing HTTP response.
• Parameter Mapping (Necessary Type: Friendly URL)
  Maps friendly URL parameters to the parameter of the DAV action. More specific, the name of the action parameter is mapped to the position of the value in the friendly URL.
  The object on which the DAV action is called can also be specified using the keyword "this" as action parameter. In this case, the specific URL parameter has to be a valid object address.
  Example: http://localhost/fsc/friendlyurl/param1/COO.1.1.1.1/param2
  If the second URL parameter has been configured with the action parameter "this", the object with the object address COO.1.1.1.1 is used as the object on which the DAV action is called upon.
• Allowed HTTP Methods
  Each friendly URL call is initially restricted to the HTTP methods "GET", "HEAD" and "OPTIONS". To extend this restriction, additional HTTP methods can be configured within this attribute.
  Example: For the "convert" friendly URL to function properly, the HTTP method "POST" must be configured.
  Should a non-configured HTTP method be used in a request, the request is answered with HTTP 405 "Not Allowed".
• Action Will Not Change State
  This settings only applies if “Cross Site Request Forgery” (CSRF) prevention is configured in the virtual application configuration (see FSCVAPP@1.1001:csrf and FSCVAPP@1.1001:csrffurlwhitelist of the FSCVAPP@1.1001:DefaultConfiguration for more details).
  If the action called by the friendly URL does not make changes, you may set this field to true. In that case the CSRF check is turned off for this kind of URLs. CSRF attacks specifically target state-changing requests and not theft of data, since the attacker has no way to see the response to the forged request. Therefore, if the friendly URL action (FSCOWS@1.1001:friendlyurlaction) or actions called by the friendly URL action will change any state this property must not be set to true.
  Sample configuration for CSRF with a friendly URL whitelist:
  
• HTTP Response Requires Script Execution
  This settings only applies if Content Security Policy (CSP) settings are configured in the Virtual Application Configuration (see property FSCVAPP@1.1001:cspdirectives of FSCVAPP@1.1001:DefaultConfiguration).
  Special CSP directives may be applied for friendly URL requests (e.g. you may configure that the execution of scripts should be disabled when executing requests for friendly URLs). You may set this option to true if the CSP directives of ordinary HTTP requests should be used for requests for this friendly URL, too. For a detailed description to Content Security Policy refer to: http://www.w3.org/TR/CSP2/: new window
  Sample of an appropriate CSP configuration that will not allow the execution of scripts for friendly URLs:
  
• Software Component
  The software component that has added the entry.