REST service elements

There are several internal procedures in a SuperMap iServer REST service: verification, decoding an HTTP, processing a request, and compiling and returning the result. These processes are accomplished by an authorizer, resources, a parameter decoder, a resource HTTP decoder, and a representation encoder in a REST service. As shown in Figure 1, a request submitted by a client to a REST server is processed by all those components. Then the processed result is generated and returned to the client.

Figure 1 Operation mechanism of internal components of a REST service

 Resource

Resources are the core components of a REST service. Every resource in a SuperMap iServer REST service has a unique URI address. Users can access resource URIs, and operate on resources through the five methods of HTTP (GET, PUT, POST, DELETE, and HEAD) to obtain results of various GIS functions. For example, performing the PUT operation on a layer resource can create or edit a map layer.

As the core elements of a service, resources are responsible for handling HTTP request contents. Specifically, a resource has the following tasks:

• Checks the content of parameter objects, and directly returns the response code corresponding to the exception when invalid parameters are detected.

• Processes the request contents using the kernel of a SuperMap iServer service--the GIS component.

• Returns the processed result containing the status parameters of the current map and so on.

Note: REST services in SuperMap iServer not only provide various default resources, such as the maps resource, the layer resource, etc., but also offer a number of abstract classes of resources, including AlgorithmResultResource, AlgorithmResultSetResource, SimpleAlgorithmResultResourceBase,  StaticResource, CatalogListResourceBase, AsynchronizedResource, and ResourceBase. If the default resources provided in SuperMap iServer do not have the specific functions the user requires, the above abstract classes can be extended to implement resources with those specific functions.

 Authorizer

REST services are web-based. Any client can access all types of resources in a REST service via URIs. Some resources even allow clients to edit the GIS data. Therefore, it is necessary to set a security mechanism on REST servers in order to protect the GIS data and prevent the REST services from being maliciously damaged.

Authorizers are specially set in the security mechanism of SuperMap iServer REST services. An authorizer must be executed first when a client's request arrives in a REST service. It mainly verifies the legitimacy of clients' identities. Only clients that pass the verification can interact with the REST service. The request from a client with an illegitimate identity is rejected. Thus an authorizer can effectively ensure the security of a REST service.

SuperMap iServer provides a default authorizer, which completes the verification process using the com.supermap.services.rest.HTTPBasicAuthorizer class. Users can retrieve this class from webapps\iserver\WEB-INF\lib\iserver-all-{version}.jar under the installation directory of SuperMap iServer. The default authorizer has the following tasks:

• Gets a list of standard identities.

• The standards for verifying identities are stored in the password.properties file, which is under config\rest in webapps\iserver\WEB-INF\lib\iserver-all-{version}.jar under the installation directory of SuperMap iServer. Users can add information to this file about many legitimate identities that can access the REST service. The information format should be [user name]=[password]. For example, "iServer=iServer123!" represents a user named "iServer" with password "iServer123!".

  The default authorizer reads the password.properties file to retrieve a list of identities that can access the REST service.

• Parses the identity information entered by a client. The default authorizer parses the information entered by a client for identity verification.

• Verifies an identity. The default authorizer compares the decoded identity information from a client with the information on the identity list. If a matching user exists in the identity list, this client's request will be transfered to the resource. Otherwise, the autorizer will generate a response code indicating that the identity submitted by the client is not legitimate, and return this response code to the client.

Figure 2 The workflow of the default authorizer

Note: SuperMap iServer provides a default authorizer to users. If a user has special requests on the authorizing condition and method, he/she can extend the class representing the default authorizer (com.supermap.services.rest.HTTPBasicAuthorizer), rewriting specific authorizing methods into the authorizer.

 Parameter decoder

The parameter decoder is used to decode map parameters contained in resource requests. Parameters are deserialized and converted to a parameter object based on which a REST service performs corresponding GIS operations.

For example, a client submits a GET request on the area resource asking for area calculation on a map. The client must submit necessary calculation parameters in the mean time, i.e., submit the node coordinates of the region to be measured. Additionally, REST services require that these necessary calculation parameters must be included in resource URIs. Thus the GET request on the area resource is:

http://localhost:8090/iserver/services/map-world/rest/maps/World Map/area.rjson?point2Ds= [{"x": 23.00,"y":34.00},{"x": 53.55,"y":12.66},{"x": 73.88,"y":12.6}]&unit=METER

where point2Ds= [{"x": 23.00,"y":34.00},{"x": 53.55,"y":12.66},{"x": 73.88,"y":12.6}]&unit=METER is the part containing parameters necessary for the resource calculation. Once the REST service receives this request, the parameter decoder deserializes the calculation parameters in the URI and converts it to a parameter object. The REST resource can then implement GIS operations with the property values in the parameter object.

SuperMap iServer provides an abstract base class representing the parameter decoder - com.supermap.services.rest.decoders.Decoder. Users can extend this parameter decoder class. It also provides a parameter decoder for JSON representations--com.supermap.services.rest.decoders.JsonDecoder, and another one for XML representations--com.supermap.services.rest.decoders.XMLDecoder. These two types of parameter decoders decode parameters from two different types of representations. Users can retrieve these classes in webapps\iserver\WEB-INF\lib\iserver-all-{version}.jar under the installation directory of SuperMap iServer.

Note: Users can extend the parameter decoder to implement custom parameter decoder methods. Usually when a user adds a custom resource to a REST service, and the parameter decoding for this resource has special rules, the parameter decoder can be extended to implement decoding the special parameters.

HTTP handler

A HTTP handler is the entrance and exit that a REST resource uses when processing a HTTP request. After being verified by the authorizer, a client's request is assigned to the corresponding resource. The HTTP handler then retrieves the HTTP request, reads and processes the request, and finally returns the final resource representation to the client.

SuperMap iServer provides a default HTTP handler - com.supermap.services.rest.DefaultMethodHandler. Users can obtain this class in webapps\iserver\WEB-INF\lib\iserver-all-{version}.jar under the installation directory of SuperMap iServer. This class has methods HandleGET, HandlePOST, HandlePUT, HandleDELETE, HandleHEAD, and HandleOptions, to process various HTTP actions. This handler processes HTTP requests on map resources, data resources, spatial analysis resources, and realspace resources in SuperMap iServer. It has the following tasks:

• Retrieves an HTTP request from a client.
• Determines whether the resource needed in the HTTP request exists. If not, it returns the client the response code indicating that the resource does not exist.
• Determines whether the REST resource supports the action needed in the HTTP request. In SuperMap iServer, every resource can only process limited actions. If the resource cannot handle the required action in the HTTP request, the HTTP handler will return the client the response code indicating that the action cannot be handled.
• Determines whether the REST resource supports the output format requested by an HTTP request. A REST resource usually supports a number of output formats, including json, xml, html, rjson, png, bmp, gif, jpg, etc. If an HTTP request requires an output format the resource doesn not support, an handler will return the client the response code indicating that the output format is not supported.
• Calls the parameter decoder to decode the parameters in an HTTP request and to convert them to a parameter object needed by the resource.
• Submits the parameter object to the resource and obtains the result processed by the resource.
• Calls the representation encoder, and compile the processed result in the required output format.
• Returns the representation to the client.

Note: The workflow of handling and responding an HTTP request is not fixed. Users may need some special processing mechanism for different service needs. Thus SuperMap iServer provides an abstract base class representing the HTTP handler--com.supermap.services.rest.AbstractMethodHandler. The default HTTP handler (DefalutMethodHandler) described above is an extended class of this abstract base class. Users can develop custom HTTP handlers that inherit the abstract base class of the HTTP handler.

Representation encoder

A representation encoder is the type of program that compiles the processed result into representation of a specified type.

In REST services, a resource returns the response result of a client's request to the client in the form of a representation. When performing a GET request, the client receives the resource representation; when performing a PUT, POST, or DELETE request, the client receives the representation of the operation result. Currently, resources in SuperMap iServer support many output formats, such as html, xml, json, rjson, png, bmp, gif, jpg/jpeg, etc., among which png, bmp, gif, jpg/jpeg are output formats for image resources. For example, Figure 3 below shows an HTML representation of the maps service, and Figure 4 shows an XML representation of the maps service.

Figure 3  The HTML representation of the maps service

 Figure 4  The XML representation of the maps service

Different types of representations need different types of representation encoders to create. Currently, SuperMap iServer provides the image representation encoder (com.supermap.services.rest.encoders.ImageEncoder, used to generate representations in formats BMP, PNG, JPEG, etc.), the JSON representation encoder (com.supermap.services.rest.encoders.JsonEncoder, used to generate representations in JSON format), the RJson representation encoder (com.supermap.services.rest.encoders.RJsonEncoder, used to generate representations in RJSON format), the XML representation encoder (com.supermap.services.rest.encoders.XMLEncoder, used to generate representations in XML format), and the template representation encoder (com.supermap.services.rest.encoders.TemplateEncoder, which generates representations based on a format specified in a template that can be designed by users themselves. HTML representations are generated using this class).

The output format is specified in the URI the HTTP request is on, through adding .<format> to the end of the URI. For example, if a GET request is performed on http://server:port/iserver/services/components-rest/rest/maps.json, the representation encoder will generate the representation of the maps resource in json format.

If no <format> is specified, the encoder will generate a representation in a default format. For GET requests, the default format of returned representation is html; for PUT, POST, and DELETE requests, the default format is rjson.

Note:

• When an error occurs during the retrieval of an image resource, the error message will be returned in html format if it is under the Debug mode (the debug field in the REST configuration in AppContext.xml is true); otherwise it is returned in json format.
• If the output formats currently provided in SuperMap iServer do not meet a user's requirement, the user can extend the abstract base class representing the encoder (com.supermap.services.rest.encoders.Encoder) and develop an encoder to accommodate his/her own needs.