API Request

Before proceeding, the reader must be familiar with the following


The URL endpoints of REST APIs created by Metamug is structured in the format {baseUrl}/{appName}/{resourceVersion}/{resourceName}. For example, a resource movie with version 1.1 in exampleApp will have URL endpoint localhost:7000/exampleApp/v1.1/movie

A request can be made to the API using XMLHttpRequest as follows

var xhr = new XMLHttpRequest();
xhr.open('GET', 'http://localhost:7000/exampleApp/v1.1/movie', true);
xhr.onload = function() {
    //after getting response
}
xhr.send();

Response types

The type of data returned in the response can be chosen by specifying the Accept header. If no Accept header is specified, the default type returned is json.

JSON response

Adding the header Accept: application/json will tell the system to return data in the JSON format

var xhr = new XMLHttpRequest();
xhr.open('GET', 'http://localhost:7000/movie/v1.1/movie', true);
xhr.setRequestHeader('Accept','application/json');
xhr.onload = function() {
    //after getting response
}
xhr.send();

The above request will fetch JSON response as follows

[
    {"id":2,"name":"The Dark Knight","rating":4.0},
    {"id":3,"name":"The Happening","rating":3.0},
    {"id":11,"name":"The Martian","rating":4.5},
    {"id":15,"name":"Rush","rating":4.0},
    {"id":16,"name":"Casino Royale","rating":4.0}
]

The JSON array can be parsed and data can be accessed as shown below

xhr.onload = function() {
    var array = JSON.parse(xhr.responseText);
    for(var i=0; i < array.length; i++) {
        var name = array[i].name;
        var rating = array[i].rating;
        //do something with the data
    }
}

JSON Dataset response

The columns and dataset can be obtained separately in the JSON object using the header Accept: application/json+dataset.

xhr.setRequestHeader('Accept','application/json+dataset');

The JSON dataset response looks as follows

{
    "columns": [
        "id",
        "name",
        "rating"
    ],
    "dataset": [
        [2,"The Dark Knight",4.0], 
        [3,"The Happening",3.0],
        [11,"The Martian",4.5],
        [15,"Rush",4.0],
        [15,"Casino Royale",4.0]
    ]
}

XML response

The same request as above made with the header Accept: application/xml will return the response in XML format.

xhr.setRequestHeader('Accept','application/xml');

The above request will fetch XML response

<data>
    <movie>
        <id>2</id>
        <name>The Dark Knight</name>
        <rating>4.0</rating>
    </movie>
    <movie>
        <id>3</id>
        <name>The Happening</name>
        <rating>3.0</rating>
    </movie>
    <movie>
        <id>11</id>
        <name>The Martian</name>
        <rating>4.5</rating>
    </movie>
    <movie>
        <id>15</id>
        <name>Rush</name>
        <rating>4.0</rating>
    </movie>
    <movie>
        <id>16</id>
        <name>Casino Royale</name>
        <rating>4.0</rating>
    </movie>
</data>

Making request with parameters

When making POST/PUT requests, Content-Type header needs to be set in the request to specify the data-format being sent in the request body.

Form parameters

For form processing, the data params are sent in form of URL encoded values e.g. name=John&age=32&gender=male

xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
xhr.send("name=John&age=32&gender=male");

JSON in request body

JSON can also be sent in the request body by setting Content-Type: application/json

var person = {name:"John", age:32, gender:"male"}
.
.
.
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.send(JSON.stringify(person));

In both the above cases, the parameters can be accessed inside the resource XML using variables $name, $age, $gender.