The Fourth International Workshop on RESTful Design, WS-REST 2013 A framework for self-descriptive RESTful services Luca Panziera and Flavio De Paoli

1. A Framework for
Self-descriptive RESTful Services
Luca Panziera and Flavio De Paoli
{panziera, depaoli}@disco.unimib.it
University of Milan-Bicocca
DISCo – Department of Computer Science, Systems and Communication
ITISlab - Innovative Technologies for Interaction and Services
WS-REST 2013 - Fourth International Workshop on RESTful
Design
@ WWW2013, 14 May 2013, Rio de Janeiro, Brazil

2. Service descriptions
 Descriptions allow for service discovery
 Automatic discovery require service descriptions
according to a common model
 Several (semantic) models and languages have
been proposed to describe services:
 WSDL 2.0
 WADL
 MicroWSMO
 hRESTS
 SA-REST
 etc.
 Very few descriptions are actually available on the
Web
No one is a de facto standard

3. Web APIs
 Most of the existing services provide Web APIs:
 Use of HTTP to tunnel procedure calls
 Unknown semantics of both operations and exchanged
data

4. Real service descriptions
 Most services are RESTful services/Web APIs
 Real information about services is available through:
 Provider documentation
 Web API repositories (e.g., ProgrammableWeb)
 Performance monitoring services
(e.g., API-status, Watchmouse)
 Social media (wikis, blogs, forums, Q&A sites)
 Information is available in:
 HTML, PDF, … (natural language)
 XML
 JSON
Heterogeneous unstructured descriptions

5. Current discovery practice
I need a music repository with
data under a free license
Result
s
“music repository with data under a free license”
WHAT?!
Ineffective Discovery!

6. Goal: Description as a Service (DaaS)
 RESTful descriptions for self-descriptive services
 Descriptions as resources
 Enabling effective discovery by humans and machines
 The approach
 Definition of techniques for delivering self-descriptive
services by extracting and publishing descriptions from
heterogeneous Web sources.
 Development of Web-based tools
 Definition of best practices for description management

7. Discovery
Engine
A new scenario
I need a music repository with
data under a free licenseRequest:
Tags: “music
repository”
Data License: “Free”
Self-descriptive services by extracting
information from the Web
Discovery engines retrive
self-descriptions as resources
Discovery of additional
information
Discogs:
Tags:
“music repository
discography”
Data License:
“Creative Commons”

8. REST in a nutshell
 Principles
 Identification of resources (URIs)
 Manipulation of resources through representations
(HTTP Methods)
 Self-descriptive messages (Internet Media Types)
 HATEOAS (Hyperlinks)
 Advantages
 Data format and model independence
 Support for discovery of resources
 More “lightweight” compared to SOAP
 Compliancy to the nature of the Web

9. Problems to support discovery
 REST Limits:
 Data format and model independence
 Discovery engines require descriptions according to a common
model
 Lack of de facto standards for implementing HATEOAS
 Then, for discovery of service information as resources
 Web Document Limits
 Heterogeneous data formats and models
 Lack of a shared vocabulary for service properties
 E.g., functionalities, licensing, QoS, service rating, usage
fees, etc.
The Solution: Definition of best practices for DaaS

10. BP1: Information modelling
 RESTful services need to be described according to
a shared and formal model that species functional
and non-functional properties.
 The definition of a sound model for representing
service properties is fundamental manipulate
descriptions exploiting the same syntax and
semantics.
 Functional properties (FPs) define functionalities provided
by a service
 Non-functional properties (NFPs) define service
characteristics that are not strictly related to the
functionality
 E.g., licensing , QoS, usage fees, etc.

11. Implementing BP1: PCM-lite
 Lightweight Policy-Centered Meta-model
 Features:
 Simple and Lightweight model
 Data Format independece
 Expressiveness
 Specification of advanced operators
 Numeric intervals
 Set theory operators
 Specification of units of
measuraments

12. BP2: Semantic data model
 Data that describes service properties need to be
represented according to RDF.
 Semantic Web standards enable:
 Advanced evaluations (e.g., subsubtion, semantic equivalence)
 To address homonymy and synonymy of terms
 Adoption of domain ontologies as vocabularies

13. Domain ontology
Implementing BP2
user:data_license
pcm-lite:hasValue
license:Free_license .
discogs:data_license
pcm-lite:hasValue
license:Creative_Commons .
Free_license
Creative_Common
s
GPLApache
is-ais-a is-a
Match!!!

14. BP3: Common vocabulary
 Property values should represent concepts that are
linked to concepts available on the Linking Open
Data Cloud.
 Linking open data cloud refers to general-purpose
ontologies to represent a vast portion of human
knowledge
 Prevention of ambiguity, synonymy and
homonymy, and thus facilitating evaluations by
automatic tools
user:data_license
pcm-lite:hasValue
dbpedia:Free_license .
discogs:data_license
pcm-lite:hasValue
dbpedia:Creative_Commons .

15. BP4: Human interpretability
 A natural language description, or label, must be
associated with each service property.
 Pure RDF documents, without natural language
descriptions, reduce human readability
discogs:policy rdfs:comment “This document describes DISCOGS RESTful APIs”.
discogs:policy pcm-lite:hasProperty discogs:tags .
discogs:policy pcm-lite:hasProperty discogs:data_license .
discogs:tags rdfs:comment
“It reppresents a set of tags that summarize service functionalities” .
discogs:tags pcm-lite:hasValue dbpedia:Music .
discogs:tags pcm-lite:hasValue dbpedia:Respository .
discogs:tags pcm-lite:hasValue dbpedia:Discography .
discogs:tags rdfs:comment “The service data is under creative commons license” .
discogs:data_license pcm-lite:hasValue dbpedia:Creative_Commons .

16. BP5: RESTful descriptions
 Services must provide descriptions as aggregations
of properties published as RESTful resources.
 HATEOAS is implemented trough links according to
Linked Data
@prefix discogs: <http://api.discogs.com/policy>
discogs:policy rdfs:comment “This document describes DISCOGS RESTful APIs”.
discogs:policy pcm-lite:hasProperty discogs:tags .
discogs:policy pcm-lite:hasProperty discogs:data_license .
http://api.discogs.com/policy
discogs:tags pcm-lite:hasValue dbpedia:Music .
discogs:tags pcm-lite:hasValue dbpedia:Respository .
discogs:tags pcm-lite:hasValue dbpedia:Discography .
http://api.discogs.com/tags
discogs:data_license pcm-lite:hasValue dbpedia:Creative_Commons .
http://api.discogs.com/data_license

17. A PCM-lite policy for the Foo service (1)
 The policy:
@prefix : <https://api.Foo.com/>
@prefix pl : <http://pcm.disco.unimib.it/pcm.lite/>
...
:fooPolicy rdf:type pl:policy.
:fooPolicy rdfs:comment ”Foo is a REST API for ... ."@en.
:fooPolicy rdfs:label "FooRESTAPI"@en.
 resources of the service
:fooPolicy pl:hasProperty :resource1.
:foopolicy pl:hasProperty :resource2.
...
 non-functional properties
:fooPolicy pl:hasProperty :datalicense.
:fooPolicy pl:hasProperty :responsetime.
...

18. A PCM-lite policy for the Foo service (2)
 A functional property as a resource: resource1
...
@prefix dbpedia : <http://dbpedia.org/resource/>
...
pl:hasValue rdf:type pl:hasRelation.
pl:hasMethod rdf:type pl:hasRelation.
...
:resource1 rdf:type pl:property.
:resource1 rdfs:comment “The 20 most recent mentions
(tweets containing a users's @screen_name)
for the authenticating user."@en.
:resource1 pl:hasValue :statuses/mentions_timeline.
:resource1 pl:hasMethod dbpedia:HTTPGET.
...

19. A PCM-lite policy for the Foo service (3)
 A non functional property as a resource: response
time
...
@prefix dbpedia:<http://dbpedia.org/resource/>
...
:responsetime rdf:type pl:property.
:responsetime rdfs:label "Service response time"@en.
:responsetime pl:hasOperator dbpedia:Less_than.
:responsetime pl:hasValue "0.153”.
:responsetime pl:hasUnit dbpedia:Second.
...

20. Making available real information as
RESTful resoureces
 Self-description wrapper
 An additional module
to service business logic
 Modelled as a RESTful
service
 Messages of the main
interface are forwared
to the wrapper

21. Discogs
discogs:license
pcm-lite:hasValue
dbpedia:
Creative_Commons .
Process of property value extraction
 The approach is based on:
 Source-to-policy templates (S2PTs)
 Named entity recongnition (NER)
S2PT:
discogs:tags
discogs:licens
e
ProgrammableWeb
document
<pw:tags>
</pw:tags>
<pw:license>
</pw:license>
“Under creative commons license”
Dbpedia Spotlight
(Named entity recognizer)

22. Scaling up Semantic Service Matchmaking
22
As of September 2010
Music
Brainz
(zitgist)
P20
YAGO
World
Fact-
book
(FUB)
WordNet
(W3C)
WordNet
(VUA)
VIVO UF
VIVO
Indiana
VIVO
Cornell
VIAF
URI
Burner
Sussex
Reading
Lists
Plymouth
Reading
Lists
UMBEL
UK Post-
codes
legislation
.gov.uk
Uberblic
UB
Mann-
heim
TWC LOGD
Twarql
transport
data.gov
.uk
totl.net
Tele-
graphis
TCM
Gene
DIT
Taxon
Concept
The Open
Library
(Talis)
t4gm
Surge
Radio
STW
RAMEAU
SH
statistics
data.gov
.uk
St.
Andrews
Resource
Lists
ECS
South-
ampton
EPrints
Semantic
Crunch
Base
semantic
web.org
Semantic
XBRL
SW
Dog
Food
rdfabout
US SEC
Wiki
UN/
LOCODE
Ulm
ECS
(RKB
Explorer)
Roma
RISKS
RESEX
RAE2001
Pisa
OS
OAI
NSF
New-
castle
LAAS
KISTI
JISC
IRIT
IEEE
IBM
Eurécom
ERA
ePrints
dotAC
DEPLOY
DBLP
(RKB
Explorer)
Course-
ware
CORDIS
CiteSeer
Budapest
ACM
riese
Revyu
research
data.gov
.uk
reference
data.gov
.uk
Recht-
spraak.
nl
RDF
ohloh
Last.FM
(rdfize)
RDF
Book
Mashup
PSH
Product
DB
PBAC
Poké-
pédia
Ord-
nance
Survey
Openly
Local
The Open
Library
Open
Cyc
Open
Calais
OpenEI
New
York
Times
NTU
Resource
Lists
NDL
subjects
MARC
Codes
List
Man-
chester
Reading
Lists
Lotico
The
London
Gazette
LOIUS
lobid
Resources
lobid
Organi-
sations
Linked
MDB
Linked
LCCN
Linked
GeoData
Linked
CT
Linked
Open
Numbers
lingvoj
LIBRIS
Lexvo
LCSH
DBLP
(L3S)
Linked
Sensor Data
(Kno.e.sis)
Good-
win
Family
Jamendo
iServe
NSZL
Catalog
GovTrack
GESIS
Geo
Species
Geo
Names
Geo
Linked
Data
(es)
GTAA
STITCH
SIDER
Project
Guten-
berg
(FUB)
Medi
Care
Euro-
stat
(FUB)
Drug
Bank
Disea-
some
DBLP
(FU
Berlin)
Daily
Med
Freebase
flickr
wrappr
Fishes
of Texas
FanHubz
Event-
Media
EUTC
Produc-
tions
Eurostat
EUNIS
ESD
stan-
dards
Popula-
tion (En-
AKTing)
NHS
(EnAKTing)
Mortality
(En-
AKTing)
Energy
(En-
AKTing)
CO2
(En-
AKTing)
education
data.gov
.uk
ECS
South-
ampton
Gem.
Norm-
datei
data
dcs
MySpace
(DBTune)
Music
Brainz
(DBTune)
Magna-
tune
John
Peel
(DB
Tune)
classical
(DB
Tune)
Audio-
scrobbler
(DBTune)
Last.fm
Artists
(DBTune)
DB
Tropes
dbpedia
lite
DBpedia
Pokedex
Airports
NASA
(Data
Incu-
bator)
Music
Brainz
(Data
Incubator)
Moseley
Folk
Discogs
(Data In-
cubator)
Climbing
Linked Data
for Intervals
Cornetto
Chronic-
ling
America
Chem2
Bio2RDF
biz.
data.
gov.uk
UniSTS
UniRef
Uni
Path-
way
UniParc
Taxo-
nomy
UniProt
SGD
Reactome
PubMed
Pub
Chem
PRO-
SITE
ProDom
Pfam PDB
OMIM
OBO
MGI
KEGG
Reaction
KEGG
Pathway
KEGG
Glycan
KEGG
Enzyme
KEGG
Drug
KEGG
Cpd
InterPro
Homolo
Gene
HGNC
Gene
Ontology
GeneID
Gen
Bank
ChEBI
CAS
Affy-
metrix
BibBase
BBC
Wildlife
Finder
BBC
Program
mes
BBC
Music
rdfabout
US Census
Media
Geographic
Publications
Government
Cross-domain
Life sciences
User-generated content
Heterogeneous sources
RDF – Linked Open Data
Service repositories
API finder
Service Descriptions
request
Best
Solution

23.  Discovery on PCM-lite descriptions is effective by the Policy Matchmaker
and Ranker for Web (PoliMaR-Web) [1].
 Some limitations for humans persist:
 RDF is less redable then HTML: poor tools for visualizzation
 Web browsers do not provide direct PUT and DELETE support to end-
users
 Then, a Web app for managing descriptions is necessary
[1] L. Panziera, M. Comerio, F. Palmonari, M. De Paoli, and C. Batini.
Quality-driven Extraction, Fusion and Matchmaking of Semantic Web API Descriptions.
Journal of Web Engineering, 11(3):247-268, 2012.
Lesson Learned: Best practices
HTTP PUT

24. Lesson Learned: the Framework
 The extraction process suffers from potential
weaknesses
 Automatic generation of S2PTs is difficult
 Heterogeneous and unspecified schema of sources requires
manual intervention any time the structure of a source changes
 Named entity recognition is not always successful
 Short textual documents may affect the techniqueExtracted
Properties
NER Precision NER Recall
Data formats 0.92 0.91
Licensing 0.79 0.78
Usage limits 0.45 0.61
Avarage 0.72 0.77

25. Conclusions and future work
 Conclusions
 Self-descriptive services enable for more effective
discovery for both humans and automatic tools
 Five best practices to exploit REST principles for
providing service descriptions
 Self-description wrappers to extract descriptions from
disperse service information sources on the Web.
 Future Work
 Automatic construction of S2PTs
 Improve NER effectiveness
 Improve the interface of the tool to support effective user
experience

26. Thank you!
Any questions?