Markus Lanthaler
ABSTRACT
Creating truly RESTful Web APIs is still more an art than a science. Developers have to struggle with a number of complex design decisions because concrete guidelines and processes are missing. Consequently, often it is decided to implement the simplest solution which is, most of the time, to rely on out-of-band contracts between the client and the server. Instead of properly modeling the application domain, all the effort is put in the design of proprietary JSON structures and URLs. This then forms the base for the contract which is communicated in natural-language (with all its ambiguity) to client developers. Since it is the server who owns the contract it may be changed at any point, which, more often than not, results in broken clients. In this position paper, we discuss some of the challenges and choices that need to be made when designing RESTful Web APIs. In particular, we compare how contracts are supposed to be established and how they are defined in practice. We illustrate the problems that are the cause of these divergences. As a first step to address these issues we describe and motivate an alternative, domain-driven approach to design Web APIs.
- S. Speicher and M. Hausenblas, "Linked Data Platform 1.0," W3C Working Draft, 2012. {Online}. Available: http://www.w3.org/TR/2012/WD-ldp-20121025/.Google Scholar
- R. T. Fielding, "Architectural styles and the design of network-based software architectures," PhD dissertation, Department of Information and Computer Science, University of California, Irvine, 2000. Google ScholarDigital Library
- "MIME Media Types," IANA. {Online}. Available: http://www.iana.org/assignments/media-types. {Accessed: 22-Feb-2013}.Google Scholar
- T. Hansen and A. Melnikov, "RFC6839: Additional Media Type Structured Syntax Suffixes," Internet Engineering Task Force (IETF) Request for Comments, 2013. {Online}. Available: http://tools.ietf.org/html/rfc6839.Google Scholar
- S. Perreault, "RFC6351: xCard - vCard XML Representation," Internet Engineering Task Force (IETF) Request for Comments, 2011. {Online}. Available: http://tools.ietf.org/html/rfc6351.Google Scholar
- C. Daboo, M. Douglass, and S. Lees, "RFC6321: xCal - The XML Format for iCalendar," Internet Engineering Task Force (IETF) Request for Comments, 2011. {Online}. Available: http://tools.ietf.org/html/rfc6321.Google Scholar
- T. Bray, D. Hollander, A. Layman, R. Tobin, and H. S. Thompson, "Namespaces in XML 1.0 (Third Edition)," W3C Recommendation, 2009. {Online}. Available: http://www.w3.org/TR/xml-names/.Google Scholar
- "IANA XML Registry," IANA. {Online}. Available: http://www.iana.org/assignments/xml-registry-index.html. {Accessed: 22-Feb-2013}.Google Scholar
- D. Raggett, A. Le Hors, and I. Jacobs, "HTML 4.01 Specification: Meta data profiles," W3C Recommendation, 1999. {Online}. Available: http://www.w3.org/TR/html401/struct/global.html#h-7.4.4.3.Google Scholar
- T. A. Inkster, "The Profile Media Type Parameter," 2009. {Online}. Available: http://buzzword.org.uk/2009/draft-inkster-profile-parameter-00.html. {Accessed: 21-Feb-2013}.Google Scholar
- E. Wilde, "RFC6906: The "profile" Link Relation Type," Internet Engineering Task Force (IETF) Request for Comments, 2013. {Online}. Available: http://tools.ietf.org/html/rfc6906.Google Scholar
- M. Nottingham, "RFC5988: Web Linking," Internet Engineering Task Force (IETF) Request for Comments, 2010. {Online}. Available: http://tools.ietf.org/html/rfc5988.Google Scholar
- C. Daboo, "jcardcal Working Group - JSON data formats for iCalendar and vCard: Proposed charter," IETF Applications Area Working Group Wiki, 2013. {Online}. Available: http://trac.tools.ietf.org/wg/appsawg/trac/wiki/jcardcal. {Accessed: 24-Feb-2013}.Google Scholar
- M. Lanthaler, "Re: {apps-discuss} iCalendar and vCard in JSON: WG draft charter," 2013. {Online}. Available: http://www.ietf.org/mail-archive/web/apps-discuss/current/msg08873.html. {Accessed: 24-Feb-2013}.Google Scholar
- H. Halpin, R. Iannella, B. Suda, and N. Walsh, "Representing vCard Objects in RDF," W3C Member Submission, 2010. {Online}. Available: http://www.w3.org/Submission/vcard-rdf/. {Accessed: 24-Feb-2013}.Google Scholar
- M. Sporny, G. Kellogg, and M. Lanthaler, "JSON-LD 1.0 " A JSON based Serialization for Linked Data," W3C Editor's Draft, 2013. {Online}. Available: http://www.w3.org/TR/json-ld/. {Accessed: 29-Mar-2013}.Google Scholar
- S. DeRose, E. Maler, D. Orchard, and N. Walsh, "XML Linking Language (XLink) Version 1.1," W3C Recommendation, 2010. {Online}. Available: http://www.w3.org/TR/xlink11/.Google Scholar
- M. Lanthaler and C. Gütl, "On Using JSON-LD to Create Evolvable RESTful Services," in Proceedings of the 3rd International Workshop on RESTful Design (WS-REST) at the 21st International World Wide Web Conference (WWW2012), 2012, pp. 25--32. Google ScholarDigital Library
- M. Lanthaler, G. Kellogg, and M. Sporny, "JSON-LD 1.0 Processing Algorithms and API," W3C Editor's Draft, 2013. {Online}. Available: http://www.w3.org/TR/json-ld-api/. {Accessed: 22-Feb-2013}.Google Scholar
- S. Parastatidis, J. Webber, G. Silveira, and I. S. Robinson, "The Role of Hypermedia in Distributed System Development," in Proceedings of the 1st International Workshop on RESTful Design (WS-REST 2010), 2010, pp. 16--22. Google ScholarDigital Library
- M. Lanthaler, "Hydra Core Vocabulary Specification," 2013 (work in progress). {Online}. Available: http://www.markus-lanthaler.com/hydra/. {Accessed: 22-Feb-2013}.Google Scholar
- T. Berners-Lee, "Principles of Design," Design Issues for the World Wide Web, 1998. {Online}. Available: http://www.w3.org/DesignIssues/Principles.html. {Accessed: 21-Feb-2013}.Google Scholar
- M. Lanthaler and C. Gütl, "Hydra: A Vocabulary for Hypermedia-Driven Web APIs," in Proceedings of the 6th Workshop on Linked Data on the Web (LDOW2013) at the 22nd International World Wide Web Conference (WWW2013), 2013.Google Scholar
- M. Lanthaler, "Leveraging Linked Data to Build Hypermedia-Driven Web APIs," in REST: Advanced Research Topics and Practical Applications, C. Pautasso, E. Wilde, and R. Alarcón, Eds. Springer, 2013 (in press).Google Scholar
- Narrative Science. {Online} Available: http://narrativescience.com/Google Scholar
Index Terms
- Model your application domain, not your JSON structures
Recommendations
On using JSON-LD to create evolvable RESTful services
WS-REST '12: Proceedings of the Third International Workshop on RESTful DesignAs the amount of data and devices on the Web experiences exponential growth issues on how to integrate such hugely heterogeneous components into a scalable system become increasingly important. REST has proven to be a viable solution for such large-...
Creating 3rd generation web APIs with hydra
WWW '13 Companion: Proceedings of the 22nd International Conference on World Wide WebIn this paper we describe a novel approach to build hypermedia-driven Web APIs based on Linked Data technologies such as JSON-LD. We also present the result of implementing a first prototype featuring both a RESTful Web API and a generic API client. To ...
The NEWT platform: an extensible plugin framework for creating ReSTful HPC APIs
GCE '14: Proceedings of the 9th Gateway Computing Environments WorkshopThis work describes the NEWT platform, a framework for creating ReSTful web APIs for high-performance scientific computing. The NEWT platform is designed to be a customizable framework that can be deployed at an HPC center, and enables access to various ...
Comments