Team Eiffel

Designing a REST based site consists of determining what the resources are for this site. And how to map them to URLs. It usually helps to actually start with URLs as the resources tend to follow from that. So the design of a web site based on REST consists of summing up the URLs and determining how many of the four verbs (GET, POST, PUT and DELETE) apply to them. And that might depend on the person doing the action, i.e. security.

Resources can also be found by listing the nouns in the requirements document of a customer. Perhaps that reminds people of a strategy advocated in the 90s when OO was all in vogue and used as a way to write a design that could be understood by these customers. We had to do that at the university: given a story about a system a customer wanted build, just extract the nouns. They were to become your classes. This was perhaps defensable as an approach for people who were totally clueless. And OOSC2 wasn't out yet.

These days we hopefully realise that such an approach is mistaken. OO is an implementation technique. Programmers use it to attain desirable program properties such as abstraction and code reuse. OO has little to do with a blueprint you would like to present to a customer. For example implementing Supplier and Customer as two separate classes is quite misguided. What happens when a Supplier also becomes a Customer?

Real world objects might map to objects used in software design, but it shouldn't be a goal in software design. Software has its own reality. Often the design improves if they don't match and if the programmer increases the abstraction level of his or her design.

This is different from resources I believe. Because resources are mapped to URLs and because URL guide customers and should be readable and understandable, resources are much closer to the reality of the customer and it is desirable to mimick that reality. It is logical for a user to go to /customers/ to see the list of customers and to go to /suppliers/ to see the list of suppliers. That underlying this is a single object called COMPANY and that a company can have the role customer or supplier or both, is an implementation technique.

So that's why EJAX is centered around resources. EJAX is an approach, an attempt to go as far as possible into a declarative way of building a web application. In deciding if URLs or resources should be the main focus, I decided on using resources. A resource can map to different URLs and that is just easier to do if resources are the things you describe and map them separately to URLs.

Here an example of the declaration of resources and the HTTP verbs that are applicable for this resource (this might depend on HTTP security):

<ejax-application>

  <resource name="suppliers">
    <url>/suppliers/</url>
    <get/>
    <put>
      <parameters>
        <parameter name="system_id">
          <data type="positiveInteger"/>
        </parameter>
        <parameter name="company_name">
          <data type="string">
            <param name="maxLength">256</param>
            <param name="whiteSpace">collapse</param>
          </data>
        </parameter>
      </parameters>
    </put>
  </resource>

  <resource name="customers/">
    <url>/customers/</url>
    <get/>
    <put>
      <parameters>
        ...
     </parameters>
    </put>
    <delete>
    </delete>
  </resource>

</ejax-application>

The parameters for a verb can be supplied in a variety of ways:

1. As part of the url, for example /customer/41 could pass 41 as the value for the parameter customer_id. The URL defined for this resource would be /customer/(customer_id).
   
2. As part of the query string, for example /customer?customer_id=41.
   
3. As a cookie.
   
4. In the body of the request if this is a POST or PUT request.

It does not really matter how the parameters are given and they can be supplied in any combination. All that matters is that they are combined into a single value space according to well-defined conflict resolution method. For example a query string parameter overrides a parameter passed in a cookie.

The definition of the parameters themselves is taken from Relax NG. Each parameter has a name and inside it follows the data tag, exactly as Relax NG defines it. The type is an XML Schema data type and the data type can have a number of parameters.

Based on this definition we can emit a CGI or Fast CGI Eiffel class that strictly validates if the verb is valid and if the passed parameters are valid.