DDR REST Service

From Morfeo Wiki

Jump to: navigation, search

Introduction

The DDR REST Service gives access to characteristics of devices. It supports the following vocabularies:

- DDR Core Vocabulary (by default)
  - Namespace: http://www.w3.org/2008/01/ddr-core-vocabulary
- MyMobileWeb
  - Namespace: http://morfeo-project.org/mymobileweb/2008/01/mymw-voc
- WURFL
  - Namespace: http://wurfl.sourceforge.net

User Manual

Meta Service

This service lists the combination of all known Properties and Aspects in all Vocabularies, and furthermore it provides the data type and default Aspect for each property
- If the client supports JSON ('application/json' in Accept HTTP Header), the Meta Service will send a JSON object as response

JSON for interchange

The format of the response is a JSON object and must conform to the following syntax (grammar for a JSON object in [1]):

  syntax
      { response : set }       
  set
      []
      [ properties ]
  properties
      { vocabularyIRI : string , propertyRefs : list }
      { vocabularyIRI : string , propertyRefs : list } , properties
  list
      []
      [ elements ]
  elements
      { propertyName : string , aspectName : string , default : boolean, dataType : string }
      { propertyName : string , aspectName : string , default : boolean, dataType : string } , elements
  boolean
      true
      false

Example

{
  response : [
      { vocabularyIRI : "http://www.w3.org/2008/01/ddr-core-vocabulary" ,
        propertyRefs : [ 
           {propertyName : "model" , dataType : "xs:string" , default : true, aspectName : "device"},
           {propertyName : "vendor" , dataType : "xs:string" , default : true, aspectName : "device"} ]
      } ]
}

XML for interchange

The format of the XML response
- XML Schema
- DTD

  <!ELEMENT response (propertyRefs*)>

  <!ELEMENT propertyRefs (propertyRef*)>                
  <!ATTLIST propertyRefs 
            vocabularyIRI %URI.datatype; #REQUIRED
  >

  <!ELEMENT propertyRef EMPTY>
  <!ATTLIST propertyRef
            propertyName  CDATA          #REQUIRED
            aspectName    CDATA          #REQUIRED
            dataType      CDATA          #REQUIRED
            default       CDATA          #IMPLIED
  >

Example

<response>
   <propertyRefs vocabularyIRI="http://www.w3.org/2008/01/ddr-core-vocabulary">
      <propertyRef aspectName="device" dataType="xs:string" default="true" propertyName="model"/>
      <propertyRef aspectName="device" dataType="xs:string" default="true" propertyName="vendor"/>
   </propertyRefs>
</response>

Query Service

The request parameter is called request

JSON for interchange

The format of the request parameter must conform to the following syntax (grammar for a JSON object in [2]):

  request
      { httpEvidence : { headers } , properties : set }
  headers    
      string : string
      string : string , headers       
  set
      []
      [ properties ]
  properties
      { vocabularyIRI : string , propertyRefs : list }
      { vocabularyIRI : string , propertyRefs : list } , properties
  list
      []
      [ elements ]
  elements       
      { propertyName : string } 
      { propertyName : string , aspectName : string }

The format of the response is a JSON object and must conform to the following syntax:

  response
      { propertyValues : set }
  set
      [ ]
      [ elements ]
  elements 
      { propertyValue : element }
      { propertyValue : element } , elements 
  element 
      string
      number
      [ items ]
      true
      false
      undefined -> when property value is NOT KNOWN
  items
      string
      string , items

The order of the property values is the same than the set of propertyRefs in the request

An example of JSON input object is described below:

{
     httpEvidence: {         
         user-agent: "Mozilla/5.0 (Windows; U; Windows NT 5.1; es-ES; rv:1.8.1.16) Gecko/20080702 Firefox/2.0.0.16"
     },     
     properties: [
         { vocabularyIRI : "http://www.w3.org/2008/01/ddr-core-vocabulary",
           propertyRefs  : [
               { propertyName  : "imageFormatSupport", aspectName    : "webBrowser" }, 
               { propertyName  : "displayHeight" } ]
         },  
         { vocabularyIRI : "http://morfeo-project.org/mymobileweb/2008/01/mymw-voc",
           propertyRefs  : [
               { propertyName  : "audioFormatSupport" } ]
         }
     ]
}

The response for the previous example:

{
     propertyValues : [ 
         { propertyValue : ["gif87","gif89a","jpeg","png","bmp"]},
         { propertyValue : 300 },
         { propertyValue : ["wav","midi","mp3","au"]}
     ]
}

XML for interchange

The format of the XML request
- XML Schema
- DTD

  <!ELEMENT request (evidences, propertyRefs)>
  
  <!ELEMENT evidences (httpEvidence*)>

  <!ELEMENT httpEvidence (#PCDATA)>
  <!ATTLIST httpEvidence
	    header CDATA #REQUIRED	      
  > 

  <!ELEMENT propertyRefs (propertyRef*)>                
  <!ATTLIST propertyRefs 
            vocabularyIRI %URI.datatype; #REQUIRED
  >
  <!ELEMENT propertyRef EMPTY>
  <!ATTLIST propertyRef
            id            ID             #REQUIRED
            propertyName  CDATA          #REQUIRED
            aspectName    CDATA          #IMPLIED      
  >

The format of the response
- XML Schema
- DTD
  - propertyValues is a node list which is returned in the order in which developer specified the propertyRefs.
    - 'pref' value is equal to 'id' attribute of 'propertyRef' element
  - An empty propertyValue element implies that the property value is NOT KNOWN

  <!ELEMENT propertyValues (propertyValue*)>
  
  <!ELEMENT propertyValue (value*)>
  <!ATTLIST propertyValue
	    pref ID #REQUIRED
  >

  <!ELEMENT value (#PCDATA)>

An example of XML input is described below:

   <?xml version="1.0" encoding="UTF-8" ?>

   <request>

     <evidences>
	<httpEvidence header="user-agent">Mozilla/5.0 (Windows; U; Windows NT 5.1; es-ES; rv:1.8.1.16)</httpEvidence>
     </evidences>

     <propertyRefs vocabularyIRI="http://www.w3.org/2008/01/ddr-core-vocabulary">	
	<propertyRef id="_1" propertyName="displayHeight" />	
	<propertyRef id="_2" propertyName="displayWidth" aspectName="device"/>			
	<propertyRef id="_3" propertyName="imageFormatSupport"  />
	<propertyRef id="_4" propertyName="displayWidth" aspectName="webBrowser"/>
     </propertyRefs>

   </request>

The response for the previous example:

   <?xml version="1.0" encoding="UTF-8" ?>

   <propertyValues>

     <propertyValue pref="_1">
        <value>300</value>
     </propertyValue>

     <propertyValue pref="_2">
        <value>240</value>
     </propertyValue>

     <propertyValue pref="_3">
        <value>gif87</value>
        <value>gif89a</value>
        <value>jpeg</value>
        <value>png</value>
        <value>bmp</value>
     </propertyValue>

     <!-- NOT KNOWN -->
     <propertyValue pref="_4" />

   </propertyValues>

Test & Service

The application can be tested in the following address [3]

The meta service is available in [4]

The query service is available in [5]

How to Install your own DDR REST Service

Download the software Device Information Simple API
Uncompress the tar.gz

Install the DDR Service app in your server
Configure the Installation_Path property (in web.xml file)

<context-param>    
  <param-name>Installation_Path</param-name>
  <param-value>D:/myServer/webapps/DDRService</param-value>
</context-param>

Configure Log4J (only File parameter and the priority, DEBUG by default)

<log4j:configuration>
  
  <appender name="rollingFile" class="org.apache.log4j.RollingFileAppender">
    <param name="File" value="C:/tmp/ddr-service.log" />
    <param name="MaxFileSize" value="512KB" />
    <param name="MaxBackupIndex" value="10" />
    <param name="Append" value="false" />
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" 
        value="[%d{dd-MM-yyyy HH:mm:ss,SSS}]   %-25.25t   %-25.25c{1} %-8p - %m%n"/>
    </layout>
  </appender>  
  
  <category name="DevInfo" additivity="false">
    <priority value="DEBUG" />
    <appender-ref ref="rollingFile"/>
  </category>
  
  <root>
    <priority value="DEBUG" />
    <appender-ref ref="rollingFile" />
  </root>
  
</log4j:configuration>

You can modify the configuration in DDR-Simple-REST-Service.xml (although we would advise this configuration by default)

<Configuration>
  <Property name="org.morfeo.devinfo.simple.data" value="resources" />

  <Property name="org.morfeo.devinfo.simple.vocabularies"
value="http://www.w3.org/2008/01/ddr-core-vocabulary, http://morfeo-project.org/mymobileweb/2008/01/mymw-voc" />

  <Property name="org.morfeo.devinfo.simple.vocabularies.default" value="http://www.w3.org/2008/01/ddr-core-vocabulary" />

  <Property name="org.morfeo.devinfo.simple.sources" value="WURFL,UAPROF" />

  <Property name="org.morfeo.devinfo.simple.timeout" value="5" />

  <Property name="org.morfeo.devinfo.simple.retry" value="5" />

  <Property name="service" value="org.morfeo.devinfo.simple.ServiceImpl" />
</Configuration>

The service can be tested from http://ip:port/DDRService
Important: if you want use WURFL as data source you have to append to JVM parameters '-Xms512m -Xmx512m'
- E.g: set JAVA_OPTS=-Xms512m -Xmx512m (catalina.bat file for example)
Important: the DDRService needs to run in a separate Tomcat instance from the web application

Source Code

The source code can be downloaded from [6]

Views

Navigation

SEARCH

TOOLBOX

LANGUAGES

Search

Toolbox

DDR REST Service

From Morfeo Wiki

Contents

Introduction

User Manual

Meta Service

JSON for interchange

XML for interchange

Query Service

JSON for interchange

XML for interchange

Test & Service

How to Install your own DDR REST Service

Source Code