WIFL is not WADL

While WIFL adopts some of the concepts of WADL, it is not a model of WADL. This document discusses the differences.

A Model of WADL

This UML class diagram is based on the WADL specification.

The Differences

The following WADL features are either not present in WIFL or are provided differently. References are provided to the WADL specification.

Cross-referencing (2.1)

Because WADL is XML-based, it must explicitly add id and href attributes to the method, param, and representation elements to allow cross-referencing between them.

These attributes are not part of the WIFL model because RDFa provides its own attributes for identification and linking and it leverages the existing HTML linking mechanisms.

Grammars (2.4)

In WADL, an XML-based representation's element attribute specifies the qualified name of its root element, which is described in a grammars element. The grammars element may contain the schema inline or refer to it from a child include element. WADL is silent about representations that are not XML-based.

A WIFL Representation's type is specified by the URI of a schema. WIFL does not require a specific set of schema types, allowing representations based on XML and those that are not.

Resources collection (2.5)

WADL has a resources element, which is a collection of resource instances that have a common base URI.

WIFL does not have a dedicated class for a collection of resources. The base URI for a set of resources may be specified by creating a "base" Resource whose path is the base URI template and setting the parent of each set member to the "base" Resource.

Sub-Resources (2.6)

In WADL, a resource may have resource children. The children are referred to as sub-resources. A sub-resource's path is constructed by concatenating the paths of its XML ancestors. This allows path components and parameters that are common to several resources to be factored out to a common ancestor resource. A sub-resource inherits its ancestors' matrix and path parameters, but not its ancestors' query or header parameters.

WIFL accomplishes WADL's sub-resource concept using a resource's parent relationship. A resource's URI template is constructed by concatenating its parent's constructed URI template and its own path property. A resource inherits its parent's path parameters.

Matrix parameters (2.6)

WADL supports matrix parameters for a resource and its sub-resources.

Matrix parameters are not supported in WIFL.

URI templates (2.6.1)

WIFL uses RFC 6570 URI templates for resources rather than WADL URI templates. WADL authors contributed to RFC 6570, which was published after WADL.

Resource types (2.7).

A WADL resource_type is a collection of WADL method and WADL resources. Setting a WADL resource R's type attribute to a WADL resource_type RT is equivalent to saying that R has the same methods and sub-resources as RT. A WADL resource has a URI template but a WADL resource_type does not. The WADL resource_type is useful for factoring out methods and sub-resources that are common to several resources which differ only in their path.

A WIFL resource inherits another resource's requests and responses by specifying that resource as the object of its super relationship. It also inherits its super's query and header parameters. (To inherit that resource's URI template and path parameters, it must be designated as the resource's parent.)

Method (2.8)

A WADL method element indicates an HTTP method (e.g. GET, POST) supported by a resource. It may contain a request and possible responses. A WADL resource may have several method elements for the same HTTP method with the difference being the input data in the request.

In WIFL, instead of a method having a request and several responses, a request has a method and several responses. The request may have several different, logically equivalent representations.

Representation Parameters (2.11.3)

A WADL representation may have zero or more WADL params, which are referred to as WADL representation parameters. A WADL Representation parameter serves one of two purposes:

  1. It defines the content of a representation. From the WADL spec, section 2.11.3:
    For representation elements with a mediaType of application/x-www-form-urlencoded or multipart/form-data the representation parameters define the content of the representation which is formatted according to the media type.
  2. It provides information about an item within the representation in two parts:
    1. The path attribute in the WADL param indicates where the item is in the representation. If the representation contains XML, the path is an XPath expression.
    2. The WADL parameter element may contain a link element that specifies the item's relationship to the resource with this representation. The link's rel and rev attributes indicate the relationship. The relationships are defined by the representation's profile attribute.

WIFL does not support representation parameters.

Parameters (2.12)

A WADL param's style attribute specifies where the parameter appears in a request or response.

In WIFL, the parameter's location is specified by its relationship with the request or response: pathParam, queryParam, or headerParam.

A WADL param's repeating attribute indicates whether the parameter takes a single value or may have multiple values.

In WIFL, a parameter's dataType property contains the URI of a specification of the parameter's possible values. That specification can indicate whether the parameter allows multiple values.

Parameter Values and Representation Expectations (2.12.3)

In WADL, it is possible to enumerate the possible values of a parameter using option children. Each option indicates a single value, and optionally, the expected media type of the response if the value is used.

In WIFL, a parameter's dataType attribute contains the URI of a specification of the parameter's possible values. WIFL does not provide a means of indicating the expected media type of a response for a particular parameter value.

Examples

WIFL provides a means of annotating examples of an API's message exchanges, identifying its requests and responses and their relevant components (method, URI, headers, body, status).

WADL does not specify a means for documenting examples.