Copyright © May 2003 Seairth Jacobs. All Rights Reserved.
Written By: Seairth Jacobs
Status: Draft
Version: 0.1
Date: July 26, 2003
Current Version: http://purl.org/rna/draft
Prior Version: http://www.seairth.com/web/rna/rna-20030529.html
RNA stands for RESTful Notification Architecture. RNA is an XML-based [XML] system for sending and receiving notifications about resources. Fundamentally, RNA works the following way:
A "notification" is created that contains a URI of a resource, as well as some additional metadata about the notification (and possibly the resource itself). The notification is then sent to each intended recipient URI. The recipient(s) then examines the notification and use the information to access the resource.
This simple architecture effectively separates the notification of a resource from the resource itself. This approach has several advantages over systems that send both the notification and the resource at the same time:
As the name indicates, RNA is based on the REST [REST] architectural style. This is achieved in several ways. First, RNA employes a stateless model. There is no need to hold informationation between requests. Second, all messages are highly visible, meaning that each message contains all information necessary to understand its purpose. Otherwise, RNA takes advantage of the already-RESTful nature of HTTP [HTTP]. RNA requests only use the POST method (all other methods are reserved for future use) and responses always use the HTTP response codes to indicate success or failure of the requests.
RNA notifications are not limited to applications where an end user will directly access the resource. For instance, two business systems could pass notifications about business documents to each other. Another example would be notifying a network-aware audio device of a new playlist from your computer (or even from some external source). The point is that anything that can send notfications and access resources can take advantage of RNA.
This specification is limited to the interaction between servers. It does not address the implementation of client or the client/server interface. The specification does address some aspects of server implementation, but in a very limited fashion. It is recognized that, since HTTP is a client/server protocol, one server must act as a client to interact with another server. For the intent of this specification, however, the interaction is thought of as a "server-to-server" interaction.
RNA consists of two types of URIs:
An Identity URI is a generic identifier for a person (or any logical endpoint, such as a mailing list, computer program, etc). This URI is used within RNA for two basic purposes: negotiating Inbox URIs and identifying ones self in a notification. However, the Identity URI may also be useful to end-users. For instance, instead of typing in a person's Inbox URI (which will likely be difficult to remember), the Identity URI could be used and allow the program to look up the actual Inbox URI to submit the notification to.
An Inbox URI is used to receive notifications. It is not the same as the Identity URI. This has the advantage of allowing Inbox URIs to be revoked without losing the Identity URI. Depending on server implementation, a single Inbox URI may be issued to all parties that want to send notifications to the user, or one Inbox URI per sender may be created. It may even be possible that a mixture of the two approaches would be used (e.g. single Inbox URI for all senders within the same domain as the recipient, but individual Inbox URIs for all other senders).
note: When URIs are compared for equivalence in RNA, they are compared using simple string comparison, as defined in section 6.2.1 (Simple String Comparison) of RFC2396bis [RFC2396bis]. While it is possible that more strict comparison rules would reduce the possbility of false-negatives and false-positives, the possibility of these occurances can also be reduced by following the guidelines in Section 6.3 (Good Practices When Using URIs) of RFC2396bis [RFC2396bis].
RNA consists of two types of documents/messages:
Agreement documents are jointly created between two entities to define the relationship that allows them to send and/or receive Notification documents. Through this creation process, each entity validates the other, and may also provide an "Inbox URI" which the other entity can send Notification documents to. Notification documents are used to notify an entity about a resource by giving its URI. Additional metadata may also be provided about the notification (e.g. who it's from, when it was sent, etc.), as well as about the referenced resource.
Currently, all RNA documents have an associated MIME type of application/x.rna+xml. Once registered with IANA, the MIME type will change. Until registration, a server may also accept application/xml.
All RNA documents begin with the root element of:
<rna version="version number"> </rna>
The only attribute is the version number. This is an optional attribute which indicates the version of the specification that the RNA document conforms to. The value will be identical to the Version at the top of the document for which the RNA document conforms. If the attribute is missing, the processor may handle it according to whatever version it believes the document to be.
Within the root element, there must be either:
The <agreement> element encompasses an RNA document type called an Agreement. The <notification> element encompass an RNA document type called Notification. Each document type is explained in detail below. No extension elements are allowed within the <rna> element.
The first document type is the Agreement. This document is collaboratively built by two entities who want to share notifications. At the end of the process, both entities contain a copy of the Agreement document that indicates the Inbox URI belonging to each other. This document must be created before Notification documents can be sent between the two entities. However, once created, the same document is used for all subsequent notifications (unless an Inbox URI is revoked; see Security).
An Agreement document will look like:
<rna version="0.1">
<agreement>
<identity uri="Entity A's Identity URI"
title="Entity A's Title">
<inbox uri="Entity A's Inbox URI" />
</identity>
<identity uri="Entity B's Identity URI"
title="Entity B's Title">
<inbox uri="Entity B's Inbox URI" />
</identity>
</agreement>
</rna>
However, some variations are permitted. These variations allow for different communications needs, since it is possible that not all communication will be two-way. The variations allow for the following:
The following list defines the meaning and constraints of each allowable sub-element:
<identity>
This element indicates an entity who is part of an Agreement document. Exactly one <identity> element is required for each entity. This element may be an empty element or contain additional metadata elements within it that relate to the Identity URI.
Attributes
uri: The value of uri is the Identity URI an entity.
title: This value of title is a suggested "friendly" title. There is no requirement to use this value for any way. Further, this value should not be depended upon for validation of an agreement. In other words, just because the value says "John Smith" does not mean the associated Identity URI represents someone named John Smith. The attribute is optional.<inbox>
This element indicates the Inbox URI of the entity identified by the <identity> element which the <inbox> element is contained in. Depending on the negotiation process, this element may or may not be present. However, at least one <identity> element must contain an <inbox> element to be considered valid. No more than one <inbox> element is allow in an <identity> element. This element may be an empty element or contain additional metadata elements within it that relate to the Inbox URI.
Attributes
uri: The value of uri is the Inbox URI of the entity identified by the <identity> element which the <inbox> elements is contained in.
In an Agreement document, each entity is responsible for adding their own <identity> element. The other entity only needs to check the entry against what they believe to be true.
When Agreement documents are being generated, the responding entity must leave out any part of the agreement that it does not understand. For instance, if an entity receives a request containing a new Agreement document and an element is encountered that it does not understand, then the returned Agreement document must not contain that element (or any of the element's contents). This mechanism allows both entities to be aware of each other's understanding of the Agreement document, while also making sure that neither entity "agrees" to any part of the Agreement document it does not understand.
When two entities are negotiating an Agreement document, three general agreement patterns are allowed:
Using HTTP, here is the process for negotiating an Agreement document between two entities. The process listed shows the case where Entity A and Entity B trade Inbox URIs. However, as noted above (and in the appropriate places below), the appropriate <inbox> or <identity> element could be left out to handle the other cases. When the <inbox> element is left out, the <identity> element may be an empty element.
<rna version="0.1">
<agreement>
<identity uri="Entity A's Identity URI">
<inbox uri="Entity A's Inbox URI" />
</identity>
</agreement>
</rna>
note: If Entity A was only trying to get an Inbox URI without giving one, then Entity A would leave the <inbox> element out. If Entity A wanted to anonymously get an Inbox URI, the entire <identity> element would be left out.
<rna version="0.1">
<agreement>
<identity uri="Entity A's Identity URI">
<inbox uri="Entity A's Inbox URI" />
</identity>
<identity uri="Entity B's Identity URI">
<inbox uri="Entity B's Inbox URI" />
</identity>
</agreement>
</rna>
note: At this point, Entity B doesn't actually know that the request is coming from Entity A. As a result, even though Entity B issued an Inbox URI, it should not receive (or possibly receive as "pending") notifications on that Inbox URI until Entity A has been authenticated. Entity B should also not yet trust that the Inbox URI associated to Entity A is valid. The exception here is if Entity A had anonymously requested (and was granted) an Inbox URI from Entity B. In this case, Entity B has no way of verifying Entity A (since Entity A did not give an Identity URI), so Entity B must implicity accept any notifications received at the given Inbox URI. Regardless, since Entity A initiated the request, Entity A knows that Entity B and Entity B's Inbox URI are valid.
<rna version="0.1">
<agreement>
<identity uri="Entity A's Identity URI">
<inbox uri="Entity A's Inbox URI" />
</identity>
<identity uri="Entity B's Identity URI">
<inbox uri="Entity B's Inbox URI" />
</identity>
</agreement>
</rna>
<rna version="0.1">
<agreement>
<identity uri="Entity A's Identity URI">
<inbox uri="Entity A's Inbox URI" />
</identity>
<identity uri="Entity B's Identity URI">
<inbox uri="Entity B's Inbox URI" />
</identity>
</agreement>
</rna>
note: At this point, Entity B would also know that the Inbox URI and the Identity URI for Entity A was valid. Also, Entity B would know that the Inbox URI returned in Step 2 did go to Entity A. Had Entity A returned an error instead, Entity B would know that some portion of the document was compromised and therefore revoke the Inbox URI (as well as throw away any "pending" notifications).
The following HTTP responses are allowed when Agreement documents are submitted to an Identity URI:
The second document type is the Notification. Once an Agreement document has been established, each entity may send a Notification document to each other's Inbox URI. A Notification document consists of a single <notification> element, which indicates a notification about a resource. Each Notification document has the following format (shown with all possible sub-elements:
<rna version="0.1">
<notification uri="Unique URI">
<from uri="Sender's Identity URI" title="plaintext name" />
<to uri="URI of primary recipient" title="plaintext name" />
<cc uri="URI of secondary recipient" title="plaintext name" />
<resource uri="resource URI"
etag="ETag of the resource at the time of notification">
<copy uri="URI of a copy of the resource"
etag="ETag of original resource at the time of copy" />
</resource>
</notification>
</rna>
The <notification> element has a single attribute: uri. This attribute allows an individual notification to be assigned a unique identifier. Unlike other URIs within the specification that are restricted to the http scheme, this URI could conform to other schemes such as the urn scheme. If the http is used, the only methods defined to be usable on this URI by the recipient are the GET and HEAD methods. All methods are reserved for future use. The value is primarily intended for a recipient to distinguish between otherwise identical notifications from a sender. The sender must make sure that the same URI is never used twice for two different notifications. The sender must also make sure not to resend a notification with a different URI unless the sender wants the recipient to see the notification as a new notification.
It is also important to note that, while there is an associated URI, messages are still considered transient. In other words, the sender will keep a notification available for a reasonable amount of time, but is not required to keep it indefinitely. This differs somewhat from the permanence of the reference resource, which may vary with factors beyond the scope of this specification.
The following list defines the meaning and constraints of each allowable sub-element, though additional elements can be used through the extension technique defined below:
<from>
This element indicates who the notification is from. This use of this element is conditional on the contents of the Agreement document for the given sender and recipient. If two entities generate an Agreement document where both entities have provided an <identity> element, then this element must be given. If the Agreement document has an anonymous sender (where the sender does not have an <identity> section), then the sender must not provide a <from> element since it cannot be verified by the recipient. This element may be an empty element or contain additional metadata elements within it that relate to the sender.
Attributes
uri: This is a required attribute that contains the Identity URI of the sender of the notification.
title: This is an optional attribute that allows an association of a plaintext name to the Identity URI. This attribute is not authoritative.<to>
This element indicates a primary recipient of the notification. This element is purely informational (and therefore optional). If a notification is received which does not reference the recipient in a <to> element, the notification is still valid. If there is more than one primary recipient of the notification, a <to> element must be used for each recipient. This element may be an empty element or contain additional metadata elements within it that relate to the primary recipient.
Attributes
uri: This is a required attribute that contains the Identity URI of the recipient of the notification.
title: This is an optional attribute that allows an association of a plaintext name to the Identity URI. This attribute is not authoritative.<cc>
This element indicates a secondary recipient of the notification. This element is purely informational (and therefore optional). If a notification is received which does not reference the recipient in a <cc> element, the notification is still valid. If there is more than one secondary recipient of the notification, a <cc> element must be used for each recipient. This element may be an empty element or contain additional metadata elements within it that relate to the secondary recipient.
Attributes
uri: This is a required attribute that contains the Identity URI of the recipient of the notification.
title: This is an optional attribute that allows an association of a plaintext name to the Identity URI. This attribute is not authoritative.<resource>
This element indicates what resource the notification is about. Exactly one <resource> element is required per <notification>. This element may be an empty element or contain additional metadata elements within it that relate to the resource.
note: Since notifications have a URI, they can be resources as well. This means that a notification could be about a notification.Attributes
uri: The value of uri is the URI of the resource that the notification is about.
etag: The value of etag is the value of the ETag returned from the original resource at the time the notification was made. This can be used to determine whether two notifications of the same resource are actually duplicates. Conversely, the ETag can be used to send repeating notifications of a single resource as it is updated. If the resource does not have an associated an ETag for the given URI, then the etagmust be blank or be omitted entirely. In this case of an omitted or blank etag, the recipient must rely on alternative approaches not defined by this specification to determine if the resource representation has changed or not.<copy>
This element indicates where a copy of the resource can be retrieved. Technically, the copy is of the returned representation of the resource, not of the resource itself (though it is possible that the representation and the resource are identical). The purpose of this element is to provide redundancy. Suggested practice is to always attempt to retrieve the original resource first, then fall back to the <copy> if the original is not retrievable. This is an optional element. If more than one copy of the original resource is created, a <copy> element must be used for each copy. This element may be an empty element or contain additional metadata elements within it that relate to the copy of the resource.
Attributes
uri: The value of uri is the URI of the copy of the original resource.
etag: The value of etag is the value of the ETag returned from the original resource at the time the copy was made. This can be used to determine whether the original resource has changed (and therefore indicate an "expired" copy). If the original resource did not return an ETag, then the etagmust be blank or be omitted entirely. In this case of an omitted or blank etag, the recipient must rely on alternative approaches not defined by this specification to determine if the resource representation has changed or not.
The following HTTP responses are allowed when notifications are submitted to an Inbox URI:
Some applications may want to provide more metadata than this specification allows for. As a result, RNA supports extension through XML Namespaces [XMLNS]. Namespaced elements can be added inside of just about any RNA element, unless a given element specifically forbids it. Extensions must not supercede RNA elements or the defined characteristics of the RNA architecture. Extension elements must also not contain RNA elements or attributes. When processing Agreement documents, unrecognized extension elements must be ignored as state above in the <agreement> section. When processing Notification documents, unrecognized extension elements may be ignore. However, if the application will be propagating the notification, it is recommended that the elements belonging to the unrecognized namespace be left in their original state since the recipient may understand the elements even though the intermediary does not. If an encountered extension namespace is understood by an application , it must handle all related elements according to their defined semantics. As a result, it is possible for an RNA document to be rejected based on the processing of an extension element.
Notification security all comes down to two things:
The general security mechanisms in RNA are based on the capability-based security model. In short, you cannot be sent a notification unless you first give the sender an Inbox URI to send it to. This is handled via the negotiation of an Agreement document. At the end of a successful negotiation, the following statements are true:
At any time, a recipient can revoke an Inbox URI. For instance, suppose that an Inbox URI was shared with someone you did not want to receive notifications from. Revocation would keep both the original sender and any additional senders from sending you a notification. The original sender must then go through the negotiation of a new Agreement document (if you want to).
Ideally, all RNA messages should be sent over a secure connection such as SSL or TLS. Otherwise, it would be possible for malicious entities to discover your Inbox URI(s), then send notification by impersonating known senders. Not all systems will provide this level of security. However, the capability can be added to any of these systems without any change to the way in which RNA works. The means that each system can weigh the pros and cons of secure connections and make the choice the feel is best for them.
Inbox URIs can be implemented in various ways that allow additional security measures to be put in place. For instance, suppose you are using RNA in a business setting. When someone outside the company wants to send notifications to an employee, the employee could issue an Inbox URI belonging to a "security appliance" that would perform additional security checks on incoming notifications. Once the notification has been cleared/validated/whatever, it can then be passed on to an "internal" Inbox URI set up between the recipient and the security appliance.
If a resource must be accessible only to the recipient of the notification pointing to it, then it is recommended that a user/password pair be assigned by the sender and passed within the URI (e.g. http://user:pwd@site.com/path). The user/password pair are nothing more than a unique key. This format allows efficient server caching of the resource (if used). Placing a unique key within the URI path would mean that devices such as caching proxies would not be able to efficiently cache the same resource because of the varying URIs. Either technique, however, allows revocation of the URI if needed. As with the notifications, maximum security requires the resource being passed over a secure channel.
note: The use of SSL does not allow for server caching. As a result, if resources are going to be accessed over such a connection, the second approach of placing the unique key within the URI path may be a better approach.
Examples 1-3 demonstrate various types of Agreement documents being created. Examples 4 and on demonstrate different ways that notifications might be used. It is important to note that this is NOT an exhaustive list of the possibilities.
In this scenario, Ann wants to send notifications to Bob (and vice versa):
<rna version="0.1">
<agreement>
<identity uri="http://myrna.net/ann">
<inbox uri="http://myrna.net/ann/12345" />
</identity>
</agreement>
</rna>
<rna version="0.1">
<agreement>
<identity uri="http://myrna.net/ann">
<inbox uri="http://myrna.net/ann/12345" />
</identity>
<identity uri="http://rnaserv.net/bob">
<inbox uri="http://rnaserv.net/bob/67890" />
</identity>
</agreement>
</rna>
<rna version="0.1">
<agreement>
<identity uri="http://myrna.net/ann">
<inbox uri="http://myrna.net/ann/12345" />
</identity>
<identity uri="http://rnaserv.net/bob">
<inbox uri="http://rnaserv.net/bob/67890" />
</identity>
</agreement>
</rna>
In this scenario, Ann wants to get news notifications from a news service called RNANews.com:
<rna version="0.1">
<agreement>
<identity uri="http://myrna.net/ann">
<inbox uri="http://myrna.net/ann/23456" />
</identity>
</agreement>
</rna>
<rna version="0.1">
<agreement>
<identity uri="http://myrna.net/ann">
<inbox uri="http://myrna.net/ann/12345" />
</identity>
<identity uri="http://RNANews.com/breakingNews" />
</agreement>
</rna>
<rna version="0.1">
<agreement>
<identity uri="http://myrna.net/ann">
<inbox uri="http://myrna.net/ann/12345" />
</identity>
<identity uri="http://RNANews.com/breakingNews" />
</agreement>
</rna>
In this scenario, Ann wants to send suggestions to a search engine called RNAIndex.net:
<rna version="0.1">
<agreement>
<identity uri="http://myrna.net/ann" />
</agreement>
</rna>
<rna version="0.1">
<agreement>
<identity uri="http://myrna.net/ann" />
<identity uri="http://RNAIndex.net/suggestions">
<inbox uri="http://RNAIndex.net/inbox/56789" />
</identity>
</agreement>
</rna>
<rna version="0.1">
<agreement>
<identity uri="http://myrna.net/ann" />
<identity uri="http://RNAIndex.net/suggestions">
<inbox uri="http://RNAIndex.net/inbox/56789" />
</identity>
</agreement>
</rna>
In this scenario, Ann wants to send a message to Bob. This is based on the Agreement document in Example 1:
<rna version="0.1">
<notification>
<from uri="http://myrna.net/ann" title="Ann Jones" />
<resource uri="http://myrna.net/ann/msg/1234" />
</notification>
</rna>
<rna version="0.1">
<notification>
<from uri="http://myrna.net/ann" title="Ann Jones" />
<resource uri="http://myrna.net/ann/msg/1234">
<copy uri="http://rnaserv.net/bob/in/4534/msg" etag="20030430092134"/>
</resource>
</notification>
</rna>
Step 1 and steps 3 through 5 are not part of the RNA specification. What happens with the notification before it's sent and after it's received is up to the server implementations. All that's required is that the notification being exchanged (step 2) is in accordance to the specification.
In this example, a notification is sent about a resource that Ann did not create (and does not have any control over):
<rna version="0.1">
<notification>
<from uri="http://myrna.net/ann" title="Ann Jones/>
<resource uri="http://www.cnn.com/" />
</notification>
</rna>
In this scenario, Bob wants to post notifications to a mailing list, http://rnalists.com/rna-dev. First, Bob would go through the negotiation process above to establish an Agreement document. The resulting document would look like:
<rna version="0.1">
<agreement>
<identity uri="http://rnaserv.net/bob">
<inbox uri="http://rnaserv.net/bob/67890" />
</identity>
<identity uri="http://rnalists.com/rna-dev">
<inbox uri="http://rnalists.com/rna-dev/inbox/339342" />
</identity>
</agreement>
</rna>
<rna version="0.1">
<notification>
<from uri="http://rnaserv.net/bob" title="Bob Smith"/>
<resource uri="http://rnaserv.net/bob/msg/45678" />
</notification>
</rna>
<rna version="0.1">
<notification>
<from uri="http://rnalists.com/rna-dev" />
<resource uri="http://rnaserv.net/bob/msg/45678">
<copy uri="http://rnalists.com/rna-dev/copy/43492" />
</resource>
</notification>
</rna>
You will notice that the list server makes a copy of the resource. Again, due to the unreliability of the Web, this allows the list to make a copy in case the original resource becomes unavailable. This may be particularly important if the list maintains an "archive" which could outlast the existance of the original resource. The notification sent by the list is not the same notification sent by the sender. The first notification was to the list, not its members. The list generated its own notification. Notice that from the list's perspective, it is sending a notification of a resource it did not create. This is no different than in Example 2, where a link to "http://www.cnn.com" was sent.
In this example, Ann is providing additional information from the Dublin Core [DC] vocabulary:
<rna version="0.1" xmlns:dc="http://purl.org/dc/elements/1.1/">
<notification>
<from uri="http://myrna.net/ann" title="Ann Jones"/>
<resource uri="http://myserv.net/ann/msg/1234">
<dc:subject>All about RNA</dc:subject>
<dc:creator>http://mysrv.net/ann</dc:creator>
<dc:format>text/html</dc:format>
<dc:format>text/xhtml+xml</dc:format>
</resource>
<dc:publisher>MyRNA Agent 1.0</dc:publisher>
<dc:date>2003-05-07T13:03:66Z</dc:date>
</notification>
</rna>
Ann wants to create a resource that only Bob can view. Ann creates the resource and assigns a random user/password pair for Bob. Ann then submits the following notification to http://rnaserv.net/bob/67890:
<rna version="0.1">
<notification>
<from uri="http://myrna.net/ann" />
<resource uri="http://blah:3495962334@myserv.net/ann/msg/1234" />
</notification>
</rna>
When Bob attempts to retrieve the resource, he is confronted with a 401 response (and appropriate www-authenticate challenge). Bob uses the provided user (blah) and password (3495962334) to authenticate himself and access the resource.
I'd like to thank the following people for their help and suggestions:
Michael Day
Tyler Close
Mike Dierken
Chuck Hinson
Walden Mathews
I'd also like to thank all the member of the rest-discuss, rest-explore, and rest-messaging mailing lists that have helped me understand REST.
By using and/or copying this document, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:
Permission to copy and distribute the contents of this document in any medium for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the document, or portions thereof, that you use: (1) A link or URL to the original document, (2) the copyright notice, and (3) the status of this document. When space permits, inclusion of the full text of this License should be provided.
No right to create modifications or derivatives of this document is granted pursuant to this license without specific, written prior permission.
THIS DOCUMENT IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.
The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders.