The document proposes a semantic description language (SEREDASj) to provide machine-readable descriptions of RESTful web services. It aims to address the lack of standards for describing REST APIs and help combat "semaphobia", the fear of semantics. The language builds on previous work but is tailored specifically for REST by focusing on simplicity and supporting many use cases including discovery and composition of RESTful services.

1. A Semantic Description Language for
RESTful Web Services
to Combat Semaphobia
Markus Lanthaler
Graz University of Technology

2. Web services are increasingly popular

3. Why do we Why do we
need a website? need an API?
1995 2000 2005 2010
Of course we Of course we
have a website have an API
Adapted from T. Vitvar’s and J. Musser’s ECOWS 2010 Keynote,
“ProgrammableWeb.com: Statistics, Trends, and Best Practices”

4. Lightweight semantic annotations
start to gain acceptance

5. Increasing interest in the relationship of
RESTful services and Linked Data

7. Need a machine-readable
service description
© Clever Cupcakes

8. © Nesster
All previous efforts assume
RPC-style. REST is different.

9. Semaphobia!?

10. simplicity
son

11. Metadata Element description
Model
Prefixes Links Type ref.
Semantics Properties Items
Media type &
Prefix Name URI Target SEREDASj desc.
Predicate Object(s) Name
Request
Semantics
SEREDASj d.
Variables Semantics
Model
Predicate Object(s) Name Binding Predicate Object(s)
ref.

12. {
"id": 556410,
"first_name": "Markus",
"last_name": "Lanthaler",
"gender": "male",
"knows": [
{ "id": 586807, "name": "Christian Gütl" },
{ "id": 790980, "name": "John Doe" } ]
}

13. {
"id": 556410,
"first_name": "Markus",
"last_name": "Lanthaler",
"gender": "male",
"knows": [
{ "id": 586807, "name": "Christian Gütl" },
{ "id": 790980, "name": "John Doe" } ]
}
{
"meta": {
"prefixes": {
"foaf": "http://xmlns.com/foaf/0.1/",
"ex": "http://example.com/onto#",
...
},
},

14. {
"id": 556410,
"first_name": "Markus",
"last_name": "Lanthaler",
"gender": "male",
"knows": [
{ "id": 586807, "name": "Christian Gütl" },
{ "id": 790980, "name": "John Doe" } ]
}
"type": "object",
"model": "[foaf:Person]",
"properties": {
"id": {
"type": "number", "model": "[ex:id]" },
"first_name": {
"type": "string", "model": "[foaf:firstName]" },
"last_name": {
"type": "string", "model": "[foaf:surname]" },
...

15. {
"id": 556410,
"first_name": "Markus",
"last_name": "Lanthaler",
"gender": "male",
"knows": [
{ "id": 586807, "name": "Christian Gütl" },
{ "id": 790980, "name": "John Doe" } ]
}
"type": "object",
"model": "[foaf:Person]",
"properties": {
"id": {
"type": "number", "model": "[ex:id]" },
"first_name": {
"type": "string", "model": "[foaf:firstName]" },
"last_name": {
"type": "string", "model": "[foaf:surname]" },
...

16. {
"id": 556410,
"first_name": "Markus",
"last_name": "Lanthaler",
"gender": "male",
"knows": [
{ "id": 586807, "name": "Christian Gütl" },
{ "id": 790980, "name": "John Doe" } ]
}
"type": "object",
"model": "[foaf:Person]",
"properties": {
"id": {
"type": "number", "model": "[ex:id]" },
"first_name": {
"type": "string", "model": "[foaf:firstName]" },
"last_name": {
"type": "string", "model": "[foaf:surname]" },
...

17. {
"id": 556410,
"first_name": "Markus",
"last_name": "Lanthaler",
"gender": "male",
"knows": [
{ "id": 586807, "name": "Christian Gütl" },
{ "id": 790980, "name": "John Doe" } ]
}
"type": "object",
"model": "[foaf:Person]",
"properties": {
"id": {
"type": "number", "model": "[ex:id]" },
"first_name": {
"type": "string", "model": "[foaf:firstName]" },
"last_name": {
"type": "string", "model": "[foaf:surname]" },
...

18. {
"id": 556410,
"first_name": "Markus",
"last_name": "Lanthaler",
"gender": "male",
"knows": [
{ "id": 586807, "name": "Christian Gütl" },
{ "id": 790980, "name": "John Doe" } ]
}
"links": {
"/user/search{?query}": {
"mediaType": "application/json",
"seredasjDescription": "personlist.json",
"semantics": {
"[iana:relation]": "[iana:search]" },
"variables": {
"query": { "model": "[foaf:name]" }
}
},

19. {
"id": 556410,
"first_name": "Markus",
"last_name": "Lanthaler",
"gender": "male",
"knows": [
{ "id": 586807, "name": "Christian Gütl" },
{ "id": 790980, "name": "John Doe" } ]
}
"/user/{id}": {
"mediaType": "application/json",
"seredasjDescription": "#",
"variables": {
"id": {
"binding": "#properties/knows/id"
} },
"requestDescription": "#"
}
}

20. {
"id": 556410,
"first_name": "Markus",
"last_name": "Lanthaler",
"gender": "male",
"knows": [
{ "id": 586807, "name": "Christian Gütl" },
{ "id": 790980, "name": "John Doe" } ]
}

21. A person. (object)
id number
first_name string The first name of a person.
last_name string The surname of some person.
gender string The gender of this Agent (typically but
not necessarily 'male' or 'female').
knows array A person known by this person
(indicating some level of reciprocated
interaction between the parties).
A person. (object)
id number
name string A name for some thing.

23. strong emphasis on simplicity many use
cases
son
discovery and composition

24. Thank You
© 2011, Markus Lanthaler. Some Rights Reserved.
http://creativecommons.org/licenses/by-nc-sa/3.0/

25. Questions?
Markus Lanthaler
Markus.Lanthaler@student.TUGraz.at

26. Image Credits
(3) Adapted from T. Vitvar’s and J. Musser’s ECOWS 2010 Keynote,
“ProgrammableWeb.com: Statistics, Trends, and Best Practices”
(7) http://en.wikipedia.org/wiki/The_Scream
(9) http://www.flickr.com/photos/clevercupcakes/4397152402/
(10) http://www.flickr.com/photos/nesster/3168425434/

27. Bonus Slides

28. {
"id": 556410,
"first_name": "Markus",
"last_name": "Lanthaler",
"gender": "male",
"knows": [
{ "id": 586807, "name": "Christian Gütl" },
{ "id": 790980, "name": "John Doe" } ]
}
"knows": {
"type": "array",
"model": "[foaf:knows]",
"items": {
"type": "object", "model": "[foaf:Person]",
"properties": {
"id": {
"type": "number", "model": "[ex:id]" },
...

29. {
"id": 556410,
"first_name": "Markus",
"last_name": "Lanthaler",
"gender": "male",
"knows": [
{ "id": 586807, "name": "Christian Gütl" },
{ "id": 790980, "name": "John Doe" } ]
}
"knows": {
"type": "array",
"model": "[foaf:knows]",
"items": {
"type": "object", "model": "[foaf:Person]",
"properties": {
"id": {
"type": "number", "model": "[ex:id]" },
...

30. {
"id": 556410,
"first_name": "Markus",
"last_name": "Lanthaler",
"gender": "male",
"knows": [
{ "id": 586807, "name": "Christian Gütl" },
{ "id": 790980, "name": "John Doe" } ]
}
"knows": {
"type": "array",
"model": "[foaf:knows]",
"items": {
"type": "object", "model": "[foaf:Person]",
"properties": {
"id": {
"type": "number", "model": "[ex:id]" },
...

31. @base <http://example.com/user/556410> .
<#> rdf:type foaf:Person .
<#> ex:id 556410 .
<#> foaf:firstName "Markus" .
<#> foaf:surname "Lanthaler" .
<#> foaf:gender "male" .
<#> foaf:knows <#knows/0> .
<#knows/0> rdf:type foaf:Person .
<#knows/0> ex:id 586807 .
<#knows/0> foaf:name "Christian Gütl" .
<#> foaf:knows <#knows/1> .
<#knows/1> rdf:type foaf:Person .
<#knows/1> ex:id 790980 .
<#knows/1> foaf:name "John Doe" .
<http://example.com/user/586807> owl:sameAs <#knows/0> .
<http://example.com/user/790980> owl:sameAs <#knows/1> .