1.
"What will this Web API return?"
Declaratively Describing Responses
of Hypermedia-Driven Web APIs
Ruben.Taelman@UGent.be
@rubensworks
Humans and machines browse
the Web by following links
and interpreting forms/controls.
REST APIs instruct machines on API usage with hypermedia controls:
http://example.org/index
http://example.org/database
http://example.org/database?name=Ruben
My Database
Index
People
By adding response info to hypermedia controls, machines
can know the input and predict the output of an API call.
For example: GET http://example.org/database{?name} with the name parameter.
The Hydra Core vocabulary allows such hypermedia controls
to be represented declaratively in RDF.
<http://example.org/people> hydra:search _:mySearch.
_:mySearch hydra:template "http://example.org/database{?name}";
hydra:mapping [ hydra:variable "name";
hydra:property foaf:name ] ].
Problem: What is the output of the API?
Hydra only declares API input parameters, not the link with the API response.
Solutions: (non-exhaustive)
1. Custom Types
_:mySearch
a ex:PeopleNameSearch.
3. SPIN SPARQL Queries2. SHACL Shapes
_:mySearch
sh:parameter
[ sh:path ex:name ];
sh:select """
SELECT ?name WHERE {
?p foaf:name ?name. }
""".
_:mySearch
sp:resultVariables ( ex:name );
sp:where ([
sp:predicate foaf:name;
sp:object ex:name;
]).
Hardcoded clients Declarative, standard voc Declarative, non-standard voc
Machines need specific guidance
to understand these controls.
Animals with this name? People with this name? People without this name? Something else?