This series focuses on three key areas of "meta-language" for Web APIs: API Description, API Discovery, and API Profiles. You’ll see articles covering all three of these important trends as well as interviews with some of the key personalities in this fast-moving space.
This InfoQ article is part of the series “Description, Discovery, and Profiles: The Next Level in Web APIs”. You can subscribe to receive notifications via RSS.
An avid cyclist, runner and photographer, Erik Wilde was educated in Berlin and Zurich and has spent the last several years teaching at UC Berkeley in California. He’s active on several W3C and IETF committees, is a frequent reviewer for peer-reviewed papers and was part of the group that founded the WS-REST track at the annual WWW events.
He has contributed to a number of Internet standards including RFC6906 ("The Profile Link Relation Type") which was the main topic of our discussion. In early April, 2015 Erik agreed to sit down with us to talk about Profiles, Description, Documentation, Discovery, his Sedola project and the future of Web-level metadata for APIs.
InfoQ: You are listed as the sole editor on RFC6906 - "The ‘Profile’ Link Relation Type" - which was published in 2013. What was the motivation behind creating this RFC? Who is the target audience?
Erik: Profiles were meant as something that would mirror the use of the HTML4 profile attribute, but make it visible in the Web’s uniform interface, because you could identify them in HTTP link headers, or in media type parameters (if the media allowed such a parameter to be used). The main motivation at the time was the use of Atom feeds, where you can say that these are a very generic media type to expose collections, but that sometimes it may be interesting to be able to say that a feed has some additional capabilities, such as carrying content according to podcast conventions, or allowing write access according to RFC5023, the Atom Publishing Protocol (AtomPub).
InfoQ: The RFC says that Profiles "allow clients to learn about additional semantics (constraints, conventions, extensions) that are associated with the resource representation"- Why is this needed? Doesn’t the media type definition cover all that already?
Erik: Media types may have extensibility and/or openness but there is no unified way to represent specific ways in which these capabilities are used. Profiles allow you to do this. They also allow those profile identifiers to be used outside of representations, either in HTTP link headers or in media type parameters. So the idea is to make the specific ways in which media types are used better visible at the Web level.
InfoQ: You were also working on a set of standardized profiles for Atom. There, it looks like you are designing URIs that communicate capabilities. In other words, these profiles don’t point to documents, but are actually "identifiers" of a set of agreed functionality. Is that how you see profiles working in general?
Erik: Yes. The RFC clearly says that a profile URI is an identifier and must be treated as such. Specifically, it is not a link. To my mind, it is very important to always clearly distinguish between identifiers that signify meaning by value and links that signify meaning by reference. Profile URIs are identifiers.
InfoQ: From your point of view then, how should Profiles be used? Mostly as a design-time aid (e.g. humans check for returned profile strings and write their code accordingly)? Or do you see them more as a runtime aid (e.g. humans write code that will be able to recognize and react to profile strings if and when they show up in a response)?
Erik: Our idea at the time was definitely at runtime. Profiles allow clients and servers to be explicit about extensions. For example, if there were two ways in which metadata is embedded in a web page (let’s say something like vCard and Dublin Core, which have some overlaps), then - based on profiles - a client could explicitly ask for the vCard variant and, if the server understood that request, the server could send vCard instead of DC. In this particular scenario, you can look at it as HTTP content negotiation in a way that’s not based on media types, but on variations of how to use that media type.
InfoQ: So the profile identifiers give us information about features, right? So can you combine one or more profiles in a response?
Erik: Yes you can, but they all have to be listed explicitly, because profiles are not composable. For example, if you wanted to create a profile Z that was a combination of profiles X and Y, that relationship would not be represented in the profile URIs of X, Y, or Z in any way. If you wanted to represent that your resource conformed to all those profiles (X, Y, and Z), you would have to list all three URIs explicitly. If you just listed profile Z’s URI, consumers only supporting X or Y would have no way to tell that Z implies X and Y.
Profiles are simply a flat identifier space and any structure or relationship that the profiles may have (such as profiles X and Y being implied by profile Z, etc.) can be documented in the definition of the profile, but will not be represented in the identifier.
There was a bit back and forth about this when the RFC was developed as a public draft. Some people preferred the profile identifier to be hierarchical so that it would be possible to represent the structure & relation of profiles in some way. But in the end, simplicity won. So profile URIs now serve as simple signals. All the RFC says is that whatever a Profile is, it is not allowed to change the media type’s semantics, i.e. if I do not understand a Profile, I should still be able to do useful things with a representation. For example, if a feed’s profile indicates that it supports RFC5023, then a client not supporting RFC 5023 will simply not care, but nothing breaks.
InfoQ: I often make the distinction between Description (e.g. Blueprint, Swagger, RAML, etc.), Discovery (e.g. APIs.json, etc), and Profiling (ALPS, etc.) of APIs for the Web. Does that track with your thinking or are there other ways to look at this space?
Erik: Well, another difference I am often making is between “Description” and “Documentation”, and "Definition" actually is another interesting and relevant term to throw into this mix. It seems that the term “Description” is increasingly used to exclusively refer to formal descriptions such as in RDF. Personally, I think that is an overly simplified view of the world but that’s why the recent languages I have been playing around with explicitly say “Documentation” and not “Description”. I guess "Definition" then could be a more general term encompassing both descriptions (if something is formally defined) and documentations (if the definition is less formal and mostly in prose). But that’s a separate discussion to have, I guess.
InfoQ: So you think "Documentation" should be added to the list of formats and specifications for Web APIs?
Erik: From my point of view, “Documentation” (or “Description”, if you include formal ways) is what APIs essentially are built on. That has to be made available somewhere, and to me, the exact way in which APIs are documented or described should be left up to the developers, because there is no single best way to do it. It highly depends on the choice of representation format, for example. XML APIs often use sophisticated XSDs that document/describe the API models. JSON often has just human-readable documentation. RDF often has OWL models backing the API. I don’t think there is only single way to do it.
InfoQ: But if these descriptions are left to developers on a case-by-case basis, we can’t have a shared standard, right?
Erik: Not across those different ecosystems, that’s correct. It seems it’s the ultimate dream of many computer people to create the one true model language to end all others. It happens all the time. I’ve personally worked with ASN.1, UML, XML, and now RDF, and every time instead of seeing this as a DSL, there are people who say "That’s it! We’ve finally found The One!" I’ve seen this too often to subscribe to this worldview anymore, so I don’t think that there can be one standard that works well for everybody and will be shared by everybody. There simply is more than just one hammer.
InfoQ: So we should just stop trying to unify things then?
Erik: I do think is that there should be one way to create an inventory of the concepts that matter for the uniform interface. And this is where Sedola comes in. You can look at it like IANA’s registries. What’s tremendously helpful on the web today is that, if I see a new HTTP header, I can look it up in IANA’s registry. They do not make any rules about how it should be described; they simply say that it must have a name following the naming rules, and that there must be a document defining it. And then they link to that document. And that is also where the other two terms you were mentioning ("Description" and "Discovery") come into play. “Discovery” is undefined in the Profile RFC but it is helpful to have the Profile URI pointing to documentation that people can read. Now, how the profile itself is defined and documented entirely depends on the media type you are profiling and how you are doing it. It probably will look very different for HTML profiles, Atom profiles, JSON profiles, or Activity Stream profiles. Activity Streams is something I have started to think about recently because it may become the “JSON feed format”.
InfoQ: So, tell us about Sedola. This is a "Description" (or "Documentation") format, right?. Is this related to your Profiles work?
Erik: Sedola is not directly related to profiles. It’s the Service Documentation Language, and its idea is to provide an inventory of Web-level concepts that a service is exposing. So if, for example, a service uses three media types, ten link relation types, and thirteen HTTP header fields, Sedola’s job would be to publish that inventory and link to additional documentation so that somebody looking for information in context would be able to find it. In theory, it would be possible to add profile URIs to Sedola as well so that a service would be able to expose an inventory of the profiles it is using. I haven’t done that yet, though. So far all I have been playing around with are media types, HTTP header fields, and link relation types. But that’s how profiles would fit into what Sedola is doing.
InfoQ: In January 2015, Darrel Miller published a blog post on the use of Hypermedia in APIs and mentioned the use of Profiles with generic media types (like HTML, etc.). Do you think this idea is a growing trend that has a future for widely-used Web APIs? Or is this mostly an academic/technical discussion that doesn’t affect the typical Web API developer?
Erik: That’s a good question. I think generic media types (such as HTML, XML, JSON, or RDF) could benefit from some mechanism of exposing this kind of information. And in some languages, mechanisms like this are built into the language itself. For example, in XML there’s the idea of using namespaces and/or linking to an XSD that provides schema information for the XML. And maybe with the RDF Data Shapes work going on right now, this idea may gain momentum. It seems to me that the mindset is fairly different in web-level settings than in corporate environments. One reason why XML was (and is) successful and useful is that it has schema support, a solid validation model, a robust ecosystem of libraries and tools, and thus allows to test pre- and post-conditions. RDF has noticed that now and is working on Data Shapes. But the most recent work I’ve seen on that is a bit disappointing because it doesn’t seem to cover openness and extensibility. But that may still change. The working group still has to publish a first public working draft. For corporate settings, I think that a reliable way of communicating expectations and having a way to test them is something that’s often necessary and something that architecture people are looking for. That’s why, as complicated as it may sometimes be, the idea of defining XML schemas, using them for pre- and post-conditions and for validation, is a very helpful concept.
InfoQ: Markus Lanthaler authored RFC7284 - "The Profile URI Registry" back in June of 2014. That RFC seems to follow similar lines of your Atom Profile work. Were you involved in RFC7284?
Erik: Markus and I chatted about this when he was starting this work. But it’s all his work because I mostly thought that having URI as identifiers for profiles was good enough and that there was no need for a centralized registry for those URIs. The current state of that registry may be an indication that maybe I was right about that. But it may also catch on and start getting used.
InfoQ: Is the registration of known URIs a next logical step for the use of Profiles?
Erik: To me, if people care about making their profiles self-documenting and known, they will make the URIs dereferencable and discoverable and then search engines will take care of the rest. And for specific ecosystems (let’s say a singlecompany’s usage of profiles) something like Sedola may be more useful because it allows decentralized documentation. That way a company can essentially have its own Sedola-driven registry instead of having to deal with IANA procedures.
InfoQ: What do you think the future of Profiles looks like? What problems will we be able to solve that we can’t solve now? How would you like to see people using Profiles?
Erik:That’s a hard question, and a good one. Profiles are a high-level concept and can be used in different ways. To me, profiles are already used all over the web only, in most cases, it’s neither called this way nor exposed explicitly. The idea of the Profile RFC was simply to allow people to expose profiles in a simple and standardized way, if they want to.
When the JSON RFC was updated recently I tried to add a profile media type parameter to the media type registration but it did not make it. I think that would have been a good starting point for people to start seeing profiles in use on the web. But the question was "is anybody using this now?" and that wasn’t the case. So the parameter didn’t make it into the RFC.For me, the biggest potential is in environments where people want to be more specific about how exactly they are using/extending/constraining some existing media type. Profiles could be one way to do that independent of the media type. This also allows people to easily and simply expose their use of profiles on the web surface of their services.
InfoQ: Thanks for sitting down to talk about Profiles. Anything else you’d like to add?
Erik: I’d like to thank you for the opportunity to have this chat. Maybe it’s a good starting point to get a bit more momentum around this idea. If people think it’s not necessary to expose profile usage, then I guess we’re done at this point. But if people like the idea, but are missing certain bits and pieces that they also would like to use, then maybe there’s some follow-up work to do that will allow people to use profiles in a way that they find useful. I’d love to get some feedback from your readers and see if there’s an opportunity here to improve the way in which web services work, and how they expose their service surface.
About the Interviewee
Erik Wilde has worked on Web technologies and architecture throughout his professional career. He studied computer science at the Technical University of Berlin and got his Ph.D. from ETH Zürich. Since then, has been working on topics regarding structured data, service architectures, application protocols, and hypermedia systems. After getting his degree, he worked in Zürich as researcher and consultant. He joined UC Berkeley’s School of Information in 2006. After that, he joined EMC’s Content Management Division as member of the Architecture Team. Since Summer 2014, he works at Siemens' Web of Things research group in Berkeley, figuring out ways how to design robust, open, and extensible service architectures that work across Siemens' extensive product and service portfolio. As part of his professional activities outside of his specific job duties, Erik is part of numerous program committees of conferences and workshops. He also participates in standardization activities in various W3C and IETF working groups.
This series focuses on three key areas of "meta-language" for Web APIs: API Description, API Discovery, and API Profiles. You’ll see articles covering all three of these important trends as well as interviews with some of the key personalities in this fast-moving space.
This InfoQ article is part of the series “Description, Discovery, and Profiles: The Next Level in Web APIs”. You can subscribe to receive notifications via RSS.