Writing RESTful services

The Mashup Server helps you write RESTful services with relative ease, facilitated by the use of the httpMethod, httpLocation and the ignoreUncited annotations. As their names imply the httpMethod is used to specify the HTTP method to be used and the httpLocation annotation specifies how the parameters can be sent in the request URI. These two annotation helps you build truly RESTful mashups. You can have a look at the RESTSample that ships as a sample with the WSO2 Mashup Server for an illustration of the usage of these annotations.

httpMethod annotation

The httpMethod annotation helps you specify the HTTP Method under which the operation will be exposed. Supported HTTP methods are GET, POST, PUT and DELETE.

                exposeViaGET.httpMethod="GET";
                function exposeViaGET() {
                    // get something
                }

                exposeViaPOST.httpMethod="POST";
                function exposeViaPOST() {
                    // post something
                }

                exposeViaPUT.httpMethod="PUT";
                function exposeViaPUT() {
                    // put something
                }

                exposeViaDELETE.httpMethod="DELETE";
                function exposeViaDELETE() {
                    // delete something
                }
            

If the httpMethod is not specified the operation is exposed with a default HTTP method. The defaulting rule is as follows,

1. If the operation is marked as "safe" using the {function}.safe annotation the HTTP method defaults to GET (the .safe annotation defaults to false unless explicitly set).

                defaultsToGET.safe = true;
                function defaultsToGET() {
                    // returns something
                }
            

2. If the operation is not marked as safe, or marked as not safe the HTTP method defaults to POST.

                function defaultsToPOST() {
                    // do something
                }
            

httpLocation annotation

The httpLocation annotation helps you take control of the URI and expose this operation under a logical URI. It does this by specifying a pattern, or template, for serializing input parameters of the function in the request URI. Curly braces are used to specify the name of an input parameter, which determines where the instance data of that parameter appears in the path component of the request URI. In the stubs the curly brace-enclosed name is replaced with instance data in constructing the path component. Remaining input instance data (not specified byhttpLocation annotation) is serialized into the query string portion of the URI. In order for the httpLocation annotation to be effective you have to use it in conjuction with inputTypes annotation. The server needs to be aware of how to build the payload from the request URI and the inputTypes annotation makes this possible.

The following example shows the use of httpMethod and httpLocation annotations. You can try the service out on your local Mashup Server. It's shipped as the RESTSample.

                getWeather.safe = true;
                getWeather.httpMethod = "GET";
                getWeather.httpLocation = "weather/{city}";
                getWeather.inputTypes = "string";
                function getWeather(city) {
                    var details = session.get(city);
                    // return whether details of city
                    // for e.g to get the weather details of colombo you need to perform a
                    // GET on http://localhost:7762/services/samples/RESTSample/weather/colombo
                }

                POSTWeather.httpMethod = "POST";
                POSTWeather.httpLocation = "weather/{city}";
                POSTWeather.inputTypes = {"city" : "string", "weatherDetails" : "string"};
                function POSTWeather(city, weatherDetails) {
                    // Add the weather details of city
                    // For e.g to add weather details of colombo you need to perform a POST
                    // on http://localhost:7762/services/samples/RESTSample/weather/colombo
                    // with the following payload
                    // <POSTWeather>
                    //      <city>colombo</city>
                    //      <weatherDetails>30</weatherDetails>
                    // </POSTWeather>
                }

                DeleteWeather.httpMethod = "DELETE";
                DeleteWeather.httpLocation = "weather/{city}";
                DeleteWeather.inputTypes = "string";
                function DeleteWeather(city) {
                    // Delete the weather details of city
                    // For e.g to delete the weather details of colombo you need to perform
                    // a DELETE on http://localhost:7762/services/samples/RESTSample/weather/colombo
                }

                PUTWeather.httpMethod = "PUT";
                PUTWeather.httpLocation = "weather/{city}";
                PUTWeather.inputTypes = {"city" : "string", "weatherDetails" : "string"};
                function PUTWeather(city, weatherDetails){
                    // Update the weather details of city
                    // For e.g to update the weather details of colombo you need to perform
                    // a PUT on http://localhost:7762/services/samples/RESTSample/weather/colombo with
                    // the following payload
                    // <PUTWeather>
                    //      <city>colombo</city>
                    //      <weatherDetails>35</weatherDetails>
                    // </PUTWeather>
                }
            

ignoreUncited annotation

This boolean indicates whether elements not cited in the httpLocation property MUST be appended to the request URI or ignored. If the value of this property is "false", elements not cited in httpLocation will be appended to the request URI. Otherwise, those are NOT serialized in the request URI.