Search

Edition:Futurama Webservice

Module:Futurama Webservice

User:Developer

Prerequisites

- not applicable

Introduction

Using the Futurama Web API to retrieve resources such as a File.

 

Description

This document explains how a resource can be retrieved from Futurama WebAPI, by using the GetResource webservice.

Calling the web service (SOAP)

The principal usage of the GetResource function is for retrieving files through Futurama WebAPI, that are actually contained within the configured rootpath (See: Configuration - Mapping). However, the system has been kept flexible for future expansion.

To discover the format of these messages, you can access the WSDL by calling the following URL as soon as you have a running FICO-enabled Futurama Webservice installation:

http://{hostname}/{applicationpath}/WebAPIService.svc?wsdl

The SoapAction to use is called “http://www.ActuIT.nl/Futurama/WebAPI/2014/10/IWebAPIService/GetResource”, the Operation is called “GetResource”, and it accepts a Parameters-object containing the request for the desired resource. An example of a call to GetResource is shown here:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.ActuIT.nl/Futurama/WebAPI/2014/10/" 
xmlns:act="http://schemas.datacontract.org/2004/07/ActuIT.Futurama.WebAPI">
   <soapenv:Header/>
   <soapenv:Body>
      <ns:GetResource>
         <ns:Parameters>
            <act:Folder>MyFuturamaApplication</act:Folder>
            <act:Identifier>CSS\STYLE.CSS</act:Identifier>
            <act:Type>File</act:Type>
         </ns:Parameters>
      </ns:GetResource>
   </soapenv:Body>
</soapenv:Envelope>

This call would request a File “Stylesheets/STYLE.CSS” that is contained within the “MyFuturamaApplication” folder within the configured RootPath. When this call is executed, the following response would be returned:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body>
      <GetResourceResponse xmlns="http://www.ActuIT.nl/Futurama/WebAPI/2014/10/">
         <GetResourceResult xmlns:a="http://schemas.datacontract.org/2004/07/ActuIT.Futurama.WebAPI" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <a:Data>The Base64-encoded data</a:Data>
            <a:Error i:nil="true"/>
            <a:MimeType>text/css</a:MimeType>
         </GetResourceResult>
      </GetResourceResponse>
   </s:Body>
</s:Envelope>

The input parameters will consist of an object with the following properties:

  • Folder: The folder present within the configured rootpath. This should be the folder that contains the Futurama Application. The value of this parameter is only applicable in the situation that the resource must be retrieved of a file within the application folder. For other resources (i.e. resources that are part of the Futurama installation, or resources that are automatically created by Futurama) this parameter is not used. The parameter value can be empty, or for example equal to the folder that contains the Futurama Application. The advantage of the last situation is that for all the GetResource calls the value of the Folder parameter can be the same.  
  • Type: This is the type of resource to be retrieved. At the current time, the only allowable value for this field is “File”.
  • Identifier: This is the identifier with which the resource can be found. When the Type is set to “File”, then the Identifier field should contain the relative path to the desired file. See the paragraph 'Restrictions in identifier' below for restrictions of this identifier.

The resulting output consists of a GetResourceResult object with the following properties:

  • Data: This field contains Base64 encoded binary data for the requested resource.
  • Error: This field contains any error messages that might have occurred.
  • MimeType: This field contains the mimetype for the requested resource. In the example above, the mimetype is text/css, indicating a stylesheet.

Calling the Web service (REST)

Using the same functionality using a REST methodology is achieved by posting data to the relative URL ‘/rest/getresource’. The posted data should contain the fields that are specified above, with the corresponding content-type.

For instance, for the content-type “application/json”, the posted data should look like this:

{
   "Folder": "Savingsaccount",
   "Identifier": "GRAPHICS/CALCULATE.PNG",
   "Type": "File"
}

And the response would look like this:

{
   "MimeType": "image/png",
   "Data": "the base64 encoded data",
   "Error": null
}

For the same request in the content-type "application/xml", the posted data should look like this:

<ResourceParameters xmlns="http://schemas.datacontract.org/2004/07/ActuIT.Futurama.WebAPI">
    <Folder>Savingsaccount</Folder>
    <Identifier>GRAPHICS/CALCULATE.PNG</Identifier>
    <Type>File</Type>
</ResourceParameters>

And the response would look like this:

<Resource xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays" xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/ActuIT.Futurama.WebAPI">
   <Data>/* the base64 encoded data */</Data>
   <Error i:nil="true"/>
   <MimeType>image/png</MimeType>
</Resource>

Restrictions in identifier

The identifier is the name of the resource to be retrieved including the path of this resource. There are some restrictions of this path. It is not allowed that the identifier consists one of the next names:

  • scripts
  • Insight
  • bin
  • FuturamaModules

So for example it is not allowed to have an application folder 'myapplication' that has a subfolder 'scripts'.

Caching policy

Because accessing the GetResource web service for every single file that is needed by a user can be a costly operation, it is advisable to use a caching system whenever these resources are requested.
For example, when a CMS plugin should be developed to access Futurama Web API, one could make a Virtual Path Provider to allow access to any files within Futurama through the GetResource function. This virtual path provider should then store/cache any retrieved files in local memory. This way whenever the same file is accessed a second time, the locally stored file can be returned, instead of a call to the Futurama Web API.

Related Topics

- Futurama Web API: Describes how Futurama Web API can be used to access a Futurama application.

Feedback

If you have any questions about this subject or if you want to provide us feedback please send us an e-mail.

Updated: 2021-03-18