ALPS - Application-Level Profile Semantics
Example: Micro-blogging with XHTML
- Author:
- Mike Amundsen (mamund@yahoo.com)
- Dates:
- 2011-02-13 (Created)
- 2011-05-04 (Updated)
- Status:
- Stable Draft
"Walking on water and developing software from a specification are easy if both are frozen."
Edward V. Berard
Discussion Group and Blog
Join the Application-Level Profile Semantics (ALPS) discussion group by visiting the
group's home page.
You can add your comments to the blog post
that first introduced this document.
General Description
The purpose of Application-Level Profile Semantics (ALPS) is to document the application-level semantics of a particular implementation.
This is accomplished by describing elements of response representations for a target media type. For example identifying markup
elements returned (i.e. semantic HTML ala Microformats) and state transitions (i.e.
HTML.A and HTML.FORM elements) that advance the state of the current application.
The example profile here contains details on customizing the XHTML media type for a
specific application domain: Micro-blogging. It contains descriptions of valid @class, @id, @name, and @rel values
that can appear within XHTML resource representations. The identified base media-type (XHTML) along with the list of attributes, values, and their
meaning describe a "hypermedia interface." This document is presented as a complete blueprint for implementing a
compliant client or server that supports the basic features of the target application domain (Micro-blogging).
It should be noted that this documentation does not contain any of the following:
- URI construction rules
- Suggested resource names
- HTTP request/response samples
- Example resource representations
This work was inspired by Roy T. Fielding's
REST APIs must be hypertext-driven.
The implementation approach is based on Tantek Çelik's
XHTML Meta Data Profiles.
Goals
- Design a document format for describing hypermedia interfaces for use in public distributed network applications.
- Discover Web developers' common assumptions when building Web client and server applications.
- Explore the challenges of designing and implementing client and server applications for the Web that can independently evolve over time.
The Experiment
As a way to test the viability of this method of documenting hypermedia interfaces, an experiment has been devised.
In this experiment, multiple parties will be asked to build their own client or server applications to match this specification;
all without seeing each other's work or accessing a running "reference" implementation.
Developers are expected to rely on the contraints and definitions found in this document (and the referenced RFCs) as the
sole instruction for building their solutions.
Compliance
An implementation is not compliant if it fails to satisfy one or more
of the MUST or REQUIRED level requirements. An implementation that satisfies all the MUST or REQUIRED
level and all the SHOULD level requirements is said
to be "unconditionally compliant"; one that satisfies all the MUST
level requirements but not all the SHOULD level requirements is said to be "conditionally compliant."
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119.
Design Characteristics
- Base Format
- XHTML
- Domain Semantics
- Specific (via ALPS)
- State Transfer
- Ad-Hoc (via HTML FORMs)
- App Flow
- Applied (via ALPS)
- H-Factors
- LO, LE, LT, LN, CM, CL
Additional Constraints
- All resource representations MUST be valid XHTML documents.
- Servers MAY require clients to support HTTP Authentication (BASIC or DIGEST) for some requests.
- Servers MAY provide additional markup or features not covered in this profile but these additions
MUST NOT contradict the semantics outlined here.
- Servers MAY supply code-on-demand elements with thier resource representations (Javascript, CSS, XSLT, etc.) but
servers SHOULD NOT assume clients will support them.
-
Servers MAY supply INPUT elements in FORMS which are not documented in this spec
and clients SHOULD(MUST?) return those INPUT elements when POSTing the FORM.
Semantic Profile
What follows is a list of XHTML attributes and their possible values. Servers SHOULD send resource representations that contain these values
along with appropriate markup and data. Servers are free to decide which elements are appropriate for each resource representation. Servers
are also free to determine which of the elements below are to be supported.
Clients SHOULD be prepared to properly handle the all attributes and elements described here. Clients SHOULD
also be prepared to provide state transfers (FORMs) back to the server as indicated.
Servers MAY provide additional semantics and clients MAY support those additional semantics.
Profile Notes
The first column contains the XHTML attribute name.
The second column contains the possible value for that attribute.
The third column contains the semantic meaning of that attribute-value pair.
The phrase "designated user" means 1) the currently authenticated
(logged-in) user; 2) a user identified via other state information (Cookies, etc.) or;
3) a user selected by some other means (following a link, etc.).
- class
-
- all
- Applied to a UL tag. A list representation of unfiltered results.
When this element is a descendent of
DIV.id="messages" it MAY have one or more
LI.class="message" descendent elements.
When this element is a descendent of
DIV.id="users" it MAY have one or more
LI.class="user" descendent elements.
- date-time
- Applied to a SPAN tag. Contains the UTC date-time the message was posted. When present, it SHOULD be valid per RFC3339.
- description
- Applied to a SPAN tag. Contains the text description of a user.
- friends
- Applied to a UL tag. A list representation.
When this element is a descendent of DIV.id="messages" it contains the list of messages
posted by the designated user's friends and
MAY have one or more LI.class="message" descendent elements.
When this element is a descendent of DIV.id="users" it contains the list of users
who are the friends of the designated user and
MAY have one or more LI.class="user" descendent elements.
- followers
- Applied to a UL tag. A list representation of all the users from the designated user's friends list.
MAY have one or more LI.class="user" descendent elements.
- me
- Applied to a UL tag.
When this element is a descendent of DIV.id="messages" it contains the list of messages
posted by the designated user and MAY have one or more LI.class="message" descendent elements.
When this element is a descendent of DIV.id="users" it SHOULD contain a single descendent
LI.class="user" with the designated user's profile.
- mentions
- Applied to a UL tag. A list representation of all the messages that mention the designated user. It MAY contain one or more
LI.class="message descendent elements.
- message
- Applied to an LI tag. A representation of a single message. It SHOULD contain the following descendent elements:
It MAY also contain the following descendent elements:
- message-post
- Applied to a FORM tag. A link template to add a new message to the system by the designated (logged-in) user.
The element MUST be set to FORM.method="post" and SHOULD contain a descendent element:
- message-reply
- Applied to a FORM tag. A link template to reply to an existing message. The element MUST be set to FORM.method="post" and
SHOULD contain the following descendent elements:
- INPUT[hidden].name="user" (the author of the post to be replied-to)
- TEXTAREA.name="message"
- message-share
- Applied to a FORM tag. A link template to share an existing message. The element MUST be set to FORM.method="post" and
SHOULD contain the following descendent elements:
- INPUT[hidden].name="user" (the author of the post to be shared)
- TEXTAREA.name="message"
- single
- When this element is a descendent of DIV.id="messages" it contains the message
selected via a message link.
SHOULD have a single LI.class="message" descendent element.
When this element is a descendent of DIV.id="users" it contains the user
selected via a user link.
SHOULD have a single LI.class="user" descendent element.
- messages-search
- Applied to a FORM tag. A link template to search of all the messages. The element MUST be set to FORM.method="get" and
SHOULD contain the following descendent elements:
- message-text
- Applied to a SPAN tag. The text of a message posted by a user.
- search
- Applied to a UL tag. A list representation of search results.
When this element is a descendent of DIV.id="messages" it contains a list of messages and
MAY have one or more LI.class="message" descendent elements.
When this element is a descendent of DIV.id="users" it contains a list of users and
MAY have one or more LI.class="user" descendent elements.
- shares
- Applied to a UL tag. A list representation of all the messages posted by the designated user that were shared by other users.
It MAY contain one or more LI.class="message" descendent elements.
- user
- Applied to an LI tag. A representation of a single user. It SHOULD contain the following descendent elements:
It MAY also contain the following descendent elements:
- user-add
-
- Applied to a FORM tag. A link template to create a new user profile.
The element MUST be set to FORM.method="post" and
SHOULD contain the following descendent elements:
It MAY also contain the following descendent elements:
- user-follow
- Applied to a FORM tag. A link template to add a user to the designated user's friend list.
The element MUST be set to FORM.method="post" and
SHOULD contain the descendent element
- user-image
-
- Applied to an IMG tag. A reference to an image of the designated user.
- user-name
-
- Applied to SPAN tag. The user's full name.
- user-text
- Applied to a SPAN tag. The user nickname text.
- user-update
-
- Applied to a FORM tag. A link template to update the designated user's profile.
The element MUST be set to FORM.method="post" and SHOULD contain the following descendent elements:
It MAY also contain the following descendent elements:
- users-search
-
- Applied to a FORM tag. A link template to search of all the users. The element MUST be set to FORM.method="get" and
SHOULD contain the descendent element:
- id
-
- messages
- Applied to a DIV tag. The list of messages in this representation. MAY have one or more of the following descendent elements:
- queries
- Applied to a DIV tag. The list of valid queries in this representation. MAY have one or more FORM and/or A
descendent elements (see "rel" and "class" section for details).
- users
- Applied to a DIV tag. The list of users in this representation. MAY have one or more of the following descendent elements:
- name
-
- description
- Applied to a TEXTAREA element. The description of the user
- email
- Applied to an INPUT[text] or INPUT[hidden] element. The email address of a user. When supplied, it SHOULD be valid per RFC5322.
- message
- Applied to a TEXTAREA element. The message to post (for the desginated user).
- name
- Applied to an INPUT[text] element. The (full) name of a user
- password
- Applied to an INPUT[password] element. The password of the user login
- search
- Applied to an INPUT[text]. The search value to use when searching messages
(when applied to FORM.class="message-search")
or when searching users
(when applied to FORM.class="users-search").
- user
- Applied to an INPUT[text] or INPUT[hidden] element. The public nickname of a user. This is the username for the user login.
- user-image
- Applied to an INPUT[file] element. The image for the user.
- website
- Applied to an INPUT[text]. The URL of a website associated with the user profile. When supplied, it SHOULD be valid per RFC3986.
- rel
-
- first
- Applied to an A tag. A reference to the first page in a list of data (messages, users)
- index
- Applied to an A tag. A reference to the starting URI for the application.
- last
- Applied to an A tag. A reference to the last page in a list of data (messages, users)
- message
- Applied to an A tag. A reference to a message representation
- message-post
- Applied to an A tag. A reference to the message-post FORM.
- message-reply
- Applied to an A tag. A reference to the message-reply FORM.
- message-share
- Applied to an A tag. A reference to the message-share FORM.
- messages-all
- Applied to an A tag. A reference to a list representation of all the messages in the system.
- messages-friends
- Applied to an A tag. A reference to a list representation of all the messages from the designated user's friends list
- messages-me
- Applied to an A tag. A reference to a list representation of all the messages posted by the designated user.
- messages-mentions
- Applied to an A tag. A reference to a list representation of all the messages that mention the designated user.
- messages-shares
- Applied to an A tag. A reference to a list representation of all the messages posted by the designated user that
were shared by other users.
- messages-search
- Applied to an A tag. A reference to the messages-search FORM.
- next
- Applied to an A tag. A reference to the next page in a list of data (messages, users)
- previous
- Applied to an A tag. A reference to the previous page in a list of data (messages, users)
- self
- Applied to an A tag. A reference to the currently loaded resource representation.
Should be applied to LINK element only OR to an A element which MUST be an immediate child of BODY element.
- user
- Applied to an A tag. A reference to a user representation
- user-add
- Applied to an A tag. A reference to the user-add FORM.
- user-follow
- Applied to an A tag. A reference to the user-follow FORM.
- user-me
-
- Applied to an A tag. A reference to the designated user's representation.
- user-update
- Applied to an A tag. A reference to the user-update FORM.
- users-all
-
- Applied to an A tag. A reference to a list representation of all the users in the system.
- users-friends
-
- Applied to an A tag. A reference to list representation of the designated user's friend users.
- users-followers
-
- Applied to an A tag. A reference to list representation of the users who follow the designated user.
- users-search
- Applied to an A tag. A reference to the users-search FORM.
- website
- Applied to an A tag. A reference to the website associated with a user.