Doctoral Dissertation Third Generation Web APIs Bridging the Gap between REST and Linked Data Markus Lanthaler Institute of Information Systems and Computer Media Graz University of Technology, Austria Supervisor: Dr.techn. Univ.-Doz. Christian Gütl Statutory Declaration I declare that I have authored this thesis independently, that I have not used other than the declared sources/resources, and that I have explicitly marked all material which has been quoted either literally or by content from the used sources. Graz, March 2014 Abstract It is becoming increasingly difficult to cope with the exponentially growing amount of data. Thus, systems are progressively being connected directly to each other to exchange, analyze, and manipulate humongous amounts of data without any human interaction. On the Web, different systems typically communicate via Web services with each other. The first generation of services was based on the flawed Remote Procedure Call (RPC) style, and was difficult to scale and maintain. Consequently, service providers started to align their offerings more closely with the architecture of the World Wide Web. Creating such services, or Web APIs as they are often called, is, however, still more an art than a science. Developers have to struggle with a number of complex design decisions and important technologies are still missing. This dissertation discusses the main issues of current Web services and related Semantic Web approaches. It reviews the state of the art and pre- sents the results of our research. Our first two contributions, namely SAPS and SEREDASj, were mainly research prototypes that acted as a proof of concept and allowed us to evaluate the main underlying ideas. Eventually, these approaches led to the creation of JSON-LD and Hydra. JSON-LD is a community effort to serialize Linked Data in JSON that resulted in a well-accepted and widely used standard. Hydra, on the other hand, is a lightweight vocabulary defining the necessary concepts to create Web APIs that fully conform to the Web’s architecture. This thesis elucidates how JSON-LD and Hydra can be used for a domain-driven design and implementation of Web APIs. To evaluate their practicality and demonstrate that they address the issues of current Web APIs, both technologies have been integrated in a current Web development framework and a completely generic client has been implemented. Finally, this dissertation also provides an overview of some early adopters and describes how they use the technologies in practice. iv Acknowledgements Even though this dissertation was written according the academic con- vention that prescribes the use of “we” instead of “I”, the “we” is justified in many occasions. Without the help and support of many people, this thesis would not have been possible. First and foremost, I would like to express my deepest gratitude to my supervisor Christian Gütl who helped me in every imaginable way, but at the same time granted me complete freedom in my research. Without his support and trust, it would never have been possible to spend most of this research abroad—literally at the other end of the world. On a related note, I would also like to thank the Curtin University for welcoming me in Australia and Chen Wu for his support during my early days in that fantastic country. I am grateful to Michael Granitzer for reviewing my first paper on Semantic Web Services and Steve Wallis for proofreading a number of papers that I wrote while I was in Australia. Over the years, I was very fortunate to collaborate with many smart peo- ple. I am proud to have worked with the JSON-LD and Hydra Commu- nity Groups, especially with Manu Sporny, Gregg Kellogg, Niklas Lindström, Dave Longley, Ruben Verborgh, Ryan J. McDonough, and Thomas Hoppe. Thank you for the countless technical discussions amidst an amicable atmosphere; that is certainly not a given if you have never met in person. I would also like to thank the RDF Working Group for accepting me despite being the youngest participant by far. Finally, I would like to thank all my new friends in the little land down under for making my stay unforgettable. A very special thanks goes to Meifania Kohn who has done a terrific job in proofreading this dissertation. Thank you buddy! I dedicate this dissertation to my family. Without their love, continuous support, and encouragement, I would certainly not be where I am today. vi Contents 1 Introduction ...................................................................................... 1 1.1 Contributions ................................................................................. 7 1.2 Outline ........................................................................................... 9 2 Basic Concepts and Technologies .................................................... 11 2.1 The Architecture of the World Wide Web .................................... 12 2.1.1 The Representational State Transfer Architectural Style ..... 16 2.2 Contracts on the Web ................................................................... 21 2.2.1 An Alternative Approach .................................................... 23 2.3 Linked Data and the Semantic Web .............................................. 25 2.3.1 The Semantic Web Technology Stack ................................ 26 2.3.1 Linked Data ....................................................................... 29 2.4 Services on the Web ...................................................................... 32 2.4.1 SOAP-based Services .......................................................... 33 2.4.2 RESTful Services ................................................................ 34 2.5 Discussion ..................................................................................... 35 3 Problem Definition ......................................................................... 37 3.1 Proprietary Data Formats and Models ........................................... 37 3.2 Static Contracts in Natural Language ............................................ 41 3.3 Manually Written Documentation ................................................ 44 3.4 The Semantic Web: Complex, Read-Only, and No Links?............ 45 3.5 Missing Tooling ............................................................................ 49 3.6 Discussion ..................................................................................... 50 4 Related Work .................................................................................. 55 4.1 Interface Description Languages .................................................... 56 4.1.1 WSDL and SAWSDL ........................................................ 57 4.1.2 WADL .............................................................................. 59 4.1.3 Swagger and Google’s API Discovery Service ..................... 60 4.1.4 SA-REST, hRESTS, and MicroWSMO ............................ 60 4.1.5 RESTdesc .......................................................................... 62 4.2 Data Interchange Formats ............................................................ 63 4.2.1 Turtle ................................................................................ 64 4.3 Vocabularies and Ontologies ........................................................ 65 4.3.1 OWL-S .............................................................................. 66 4.3.2 WSMO ............................................................................. 67 4.3.3 WSMO-Lite ...................................................................... 68 4.3.4 EXPRESS .......................................................................... 69 4.3.5 Linked Data Platform ........................................................ 70 4.4 Domain Application Protocols ..................................................... 70 4.4.1 Atom ................................................................................. 71 4.4.2 OpenSearch ....................................................................... 72 4.4.3 oEmbed ............................................................................. 73 4.5 Hyperlinks and Namespaces in JSON .......................................... 74 4.6 Discussion .................................................................................... 75 5 Bridging the Gap between REST and Linked Data ......................... 79 5.1 SAPS ............................................................................................ 81 5.1.1 Basic Concepts and Principles ............................................ 81 5.1.2 Illustrative Example ........................................................... 84 5.1.3 Integration into the Linked Data Cloud ............................ 89 5.1.4 Summary and Lessons Learned .......................................... 91 5.2 SEREDASj ................................................................................... 92 5.2.1 Basic Concepts and Principles ............................................ 93 5.2.2 Illustrative Example ........................................................... 97 5.2.3 Integration into the Linked Data Cloud .......................... 100 5.2.4 Summary and Lessons Learned ........................................ 107 5.3 JSON-LD ................................................................................... 108 5.3.1 Basic Concepts and Principles .......................................... 111 5.3.2 Illustrative Example ......................................................... 122 5.3.3 Integration into the