Resource File

Before proceeding to the following article, the reader must be familiar with the following

The REST methodology considers each data object as a resource. The name of the resource name is included in the URL and HTTP requests like GET, POST, PUT, DELETE can be made on the URL.

Metamug uses XML documents (resource files) to describe the behaviour of REST APIs. The files are used to describe the server-side operation to be performed when an HTTP request is made to a particular resource.

Collection & Item Request

movie.xml

<?xml version="1.0" encoding="UTF-8" ?>
<Resource xmlns="http://xml.metamug.net/resource/1.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://xml.metamug.net/resource/1.0 http://xml.metamug.net/schema/resource.xsd" 
     v="1.1">
    <Desc>Contains information about movies.</Desc>

    <!-- Collection GET Request /movie --> 
    <Request method="GET">
        <Desc>Get info of all movies with ratings greater than 3.</Desc>
        <Query>
            SELECT name,rating FROM movie
            where rating gt 3.0
        </Query>        
    </Request>

    <!-- Item GET Request /movie/{id} -->
    <Request method="GET" item="true">
        <Desc>Get info of movie with given id.</Desc>
        <Query>
            SELECT * FROM movie where id=$id
        </Query>
    </Request>

</Resource>

The xml document is used to describe a resource. The title of the resource file ("movie" in this case) is mapped as the name of the particular resource.

Resource Tag

<Resource> is the root element of the xml document.

Attributes

Version: Used to describe the version of the particular resource file, "1.1" in this case.

When making an HTTP request to the above resource, the version must be included in the URL in the manner {baseUrl}/v1.1/movie that is, prefixed with "v" character. Versioning can be used to implement multiple resource files.

  1. A GET request made to {baseUrl}/v1.1/movie will return all the records in the table "movie".
  2. A GET request made to {baseUrl}/v1.1/movie/1 (for example) will return only the record with id=1 (as id=$id in the SQL query) in the table "movie".

Desc Tag

<Desc> is an optional element used for describing the particular resource. The description is shown in the API documentation.

Request Tag

1.The first Request tag is used to describe an HTTP request made on a collection resource. The children of the resource tag describe the action to be performed after the request is made.

This tag represents a GET request made to {baseUrl}/movie, where "movie" is the resource name.

2.The second Request tag in the document has a new attribute item which is set to "true". This denotes a request to fetch a particular item represented by the number in the URL.

The URL in this case will look like {baseUrl}/movie/{id}. The first Request is a collection request and has no item attribute (item="false" by default) wherein the URL was simply {baseUrl}/movie.

Attributes

Query and Update Tag

The Query tag contains the SQL query to be executed on the backend database when the parent request is received. It is always a child of the Request tag. It should be used for making SELECT queries. Database writes based SQLs like INSERT, UPDATE, DELETE etc. must be wrapped inside Update tag.

Attributes

Note There is no mapping between the resource name ("movie" in this case) and the name of the database table ("movie" in this case). A SQL statement written inside a Request tag is independent of the type of HTTP request or the resource.

XML Escape Characters

In the movie.xml example above, the first SQL was written is SELECT name, rating FROM movie where rating gt 3.0. The characters gt in this SQL represent the > (greater than) symbol. Thus, the actual SQL executed will be SELECT name, rating FROM movie where rating > 3.0. The XML format does not support the following symbols and they are required to be escaped using characters as shown below:

Symbol Escape Characters
> gt
>= ge
< lt
<= le
= eq
!= ne

Updating Data

Insert, Update and Delete operations can be performed on the database using POST, PUT and DELETE requests.

movie.xml

<Request method="POST" status="201">
    <Update>
        INSERT INTO movie (name, rating) VALUES ($p, $q)
    </Update>
</Request>

<Request method="PUT" status="202" item="true">
    <Update>
        UPDATE movie SET rating=$rating WHERE id=$id
    </Update>
</Request>

<Request method="DELETE" status="410" item="true">
    <Update>
        DELETE FROM movie WHERE id=$id
    </Update>
</Request>

POST, PUT, DELETE requests for the resource can be added as shown above.

  1. POST request is made on a resource collection. The SQL statement contains two variables $p and $q. Here, "name" and "rating" are the column names of the table. A POST request made to {baseUrl}/movie with parameters p=Madagascar&q=4.5 will add a new movie record with the name as Madagascar and rating 4.5. The parameter names p and q are directly mapped with variable names $p and $q.
  2. PUT request is made on a resource item. In above example, a PUT request made to {baseUrl}/movie/2 with request parameter rating=4 will update the entry in the "rating" column, of the record with id=2, with the value 4.
  3. DELETE request is made on a resource item. A DELETE request made to {baseUrl}/movie/3 (for example) will delete the record with id=3.

Conditional Queries with when

Multiple elements can be used inside a Request tag. In such cases when attribute should be used in the Sql elements. when attribute evaluates a logical expression. On the successful evaluation of the expression, the SQL statement is executed.

Multiple Sql statements can be executed on the same request. If their respective "when" expressions evaluate to true. e.g when="amount lt 10000", when="type eq 'one' and color eq 'blue'"

movie.xml

<?xml version="1.0" encoding="UTF-8" ?>
<Resource v="1.2" xmlns="http://xml.metamug.net/resource/1.0">
    <desc>Contains information about movies.</desc>

    <Request method="GET">
        <!-- SQL 1 -->
        <Sql type="query" when="$q eq 1">
            SELECT name,rating FROM movie
        </Sql>        

        <!-- SQL 2 -->
        <Sql type="query" when="$q eq 2">
            SELECT name,rating FROM movie
            where rating=5.0
        </Sql>        

        <!-- SQL 3 -->
        <Sql type="query" when="$q eq 3">
            SELECT name,rating FROM movie
            where rating lt 3.0
        </Sql>        
    </Request>
</Resource>

In the above example, there are three Sql elements used inside a Request. A query parameter q sent in the HTTP request will determine which of the three SQL queries will be executed and the corresponding result will be returned. SQL 1 will be executed when a request is made with URI {baseUrl}/v1.2/movie?q=1 as determined by when="$q eq 1" and so on.

Its more readable to use strings wherever possible to represent your sql like when="$q eq 'all'" or when="$q eq 'sort_name'".