Accessing REST service |
REST services in SuperMap iServer have abundant contents. Services of each type contain a number of resources with corresponding GIS functions. Users can view REST service directories, service contents, as well as supported operations and output formats by directly entering a URI in a browser. In this way, users can get to know published REST service contents quickly, and obtain resource services that meet their system requirement.
SuperMap iServer organizes and publishes various resources of REST services with a certain hierarchical structure. As shown in Figure 1, users can retrieve a REST service directory through using the root resource of the REST service, to quickly locate the resource needed.
Figure 1 Illustration of the hierarchical structure of a resource
As shown in Figure 1, the "root" resource is the root resource of all REST services. The map REST services, data REST services, spatial analysis REST services, and realspace REST services provided in SuperMap iServer are all child resources of the root resource. The root resource supports the GET and HEAD operations. The GET operation can be used to retrieve the directories of all the published REST services. The HEAD request can be used to determine whether a root resource exists, or whether a client has permission to access a root resource. To perform a HEAD request on a URI containing .<format> can quickly determine whether the root resource supports output format .<format>.
Open a web browser, and enter the URI of the root resource (i.e., perform a GET operation on the root resource). The URI should be in the following format:
http://<server>:<port>/iserver/services/{component}/rest[.<format>]
For example, if http://192.168.1.1:8090/iserver/services/components-rest/rest.html is entered in the address bar, the REST service directory described in HTML format will be displayed.
It is helpful for obtaining proper REST services to understand the service contents supported by REST services before using them. The service content of a service includes the map of the service, the resource contents of the REST service, and the operations supported by the resources of the REST service.
As mentioned above, performing a GET operation on the root resource retrieves the directory of REST services. The service directory page can also be retrieved by directly entering the address of a REST service in a web browser. SuperMap iServer processes service directory pages (i.e., the HTML representations) in a way that users can directly view detailed information of a REST service by clicking on the hyperlink on that service. The detailed information includes the map name of the service, the service capability (the list of resources), etc. Similarly, for a directory resource, a directory of its child resources is listed on its description page. Clicking on each child resource can bring out the description page of that child resource. Overall, users can retrieve information on all the published REST services and resources by accessing the root resource via a web browser.
The following paragraphs describe how to retrieve REST service information using retrieval of information a map REST service as an example.
Enter the address of a REST service in a web browser, such as http://192.168.1.1:8090/iserver/services/components-rest/rest, the REST service directory will be displayed. Click on the maps resource and get to the description page of map REST services, i.e., the description page of the maps resource. As shown in figure 2, this page lists all the child resources of the maps resource, as well as the http methods and output formats supported by the maps resource. Clicking on the hyperlink of an output format will download a representation file in that format. For example, clicking on xml will download the GET representation of the maps resource in xml.
Figure 2 The maps resource
Click on World Map, the representation of the map resource in the World Map service can be seen. Information about World Map is described in the representation, such as its map extent, default center, visible extent, scale, etc. Also contained in the representation is a list of the child resources in the World Map service, including various algorithm resources, static resources, etc.
Clicking on the image resource, which is a child resource of the map resource, shows the representation of the GET operation of the current image resource. The parameters needed for the GET operation are also included on this page in an interactive fashion. Users can enter the parameter values in the boxes on the web page. Then the corresponding result can be obtained by clicking on the "Get the image" button.
The depth of HTML representations of REST services is processed in SuperMap iServer in a way that users can use a browser to quickly view the directory of published REST services, the calculation information on various algorithm resources and their parameters. Even better, REST resources can be operated on directly in a web browser in an interactively fashion.
REST services published by SuperMap iServer are real RESTful web services. Any operation on a resource is implemented through the HTTP protocol. The GET method is used to retrieve the representation of a resource; PUT is used to modify or add a resource; POST is used to add a resource; and DELETE is used to delete a resource. REST resources also support the HEAD operation, which only returns the message header without any representation. HEAD is used to retrieve a resource's metadata, including information about whether the resource is accessible, whether it supports a certain output format, etc.
All the REST resources in SuperMap iServer support the GET operation. The GET operation can be used to retrieve the representation of the resource, including the HTTP actions and the output formats supported by the resource. Performing a GET operation on a directory resource (e.g., the first-level resource of each type of REST services) retrieves its child resource list. Performing a GET operation on an algorithm resource usually retrieves the result of the algorithm. For example, performing a GET operation on the image resource can retrieve a map image.
Because GET is the default requested method when a browser sends a request to a web server, a GET operation can be directly implemented on a resource via a web browser. For example, if http://192.168.1.1:8090/iserver/services/components-rest/rest/maps/World Map/image.png is entered in the address bar of a web browser, the GET method will be performed on the image resource of World Map, and the image of World Map will be obtained.
Developers can also perform the GET operation on REST resources using various development languages (e.g., JavaScript).
The PUT method can be used to modify or add a resource. If a PUT operation is requested on a REST resource in an application system, simply entering a URI in the address bar of a web browser would not work. Instead, a development language is needed for the implementation. The body of a PUT request must contain proper parameters. If the parameters are valid, the resource will be modified and added on a SuperMap iServer server. A response code will then be returned to the client indicating whether the operation is successful. In the example below, a PUT operation is implemented on the map resource using the JavaScript language in order to change the center of World Map.
method="PUT";
//data is the parameter content.
uri="http://supermapiserver:8090/iserver/services/components-rest/rest/maps/World Map.json";
data="{\"name\":\"World Map\", \"center\":{\"x\":142, \"y\":44}}";
xmlhttp.open (method, url, false);
xmlhttp.setRequestHeader ("Content-Type", "application/x-www-form-urlencoded; charset=UTF-8");
xmlhttp.setRequestHeader ("Content-Length", data.length);
xmlhttp.send (data);
Performing a POST operation on a resource adds a resource. Different from the PUT method, POST adds a resource by sending a request to an existing URI, whereas the PUT method sends a request to a non-existing URI. For example, suppose it is requested to add a layer to a layers resource (a set of layers). Because a layers resource has an existing URI, this operation has to be implemented using the POST method. If a layer is to be added to a layer resource, the PUT method should be used.
As with the PUT method, a development language needs to be employed when a POST operation on a REST resource is needed in an application system. Similarly, the parameters related to the request need to be contained in the body of the POST request.
Performing a DELETE operation on a resource deletes this resource. Again, a development language needs to be employed when a DELETE operation on a REST resource is needed in an application system.
Performing the HEAD operation returns the same HTTP response header as GET does, but no response entity is included. HEAD request can be used to get metadata from the response message header without transporting the entire response content. Metadata includes information about the media type, character encoding, compression encoding, the length of the entity content, etc.
HEAD request can be used to check if a resource exists, or if a resource can be accessed by clients. It can also quickly determine if a resource supports an output format <format> if performed on a URI with .<format> included.
When a client sends an HTTP request to a SuperMap iServer server, the server returns the response result in the requested format. Through the response code included in the response result, the client can get the condition of the request processing, such as whether it is successful, and the cause of failure if it is not.
The HTTP protocol defines the meaning of each response code. There are 41 officially defined response codes. SuperMap iServer mainly uses the 2xx series, the 4xx series, and the 5xx series. The meaning of each response code is listed in the following table:
|
Response code value |
Description |
| 200 |
Indicates that the server has successfully implemented the HTTP request from the client. If the request type is GET, this code indicates that the resource is successfully retrieved; if the request is PUT, it indicates that the resource has been successfully modified; if the request if DELETE, it indicates that the resource is successfully deleted; if the request if HEAD, it indicates that the metadata of the resource is successfully retrieved. |
| 201 |
Indicates that a new resource has been successfully created according to a client's request. The corresponding request type is POST or PUT. Note that the returned information only contains the Location header that points at the standard URI of the newly created resource. |
| 400 |
Indicates that the request parameters provided by the client are not valid or not sufficient. For example, performing the POST operation on a layers resource creates a new layer, i.e., a layer resource. But if no necessary parameters are provided in the request body for creating the new layer, that is, no description information of the layer is provided, response code 400 will be returned. |
| 401 |
Indicates that the operation on the resource is not completed due to security reasons. For example, performing a POST request (with parameters provided) on a layers resource creates a new layer. The corresponding URI is: http://<server>:<port>/iserver/services/{component}/rest/maps/World Map/layers.json To create a new layer requires the administrator's permission. If a client does not have that permission, it will get response code 401 when performing the above request. |
| 404 |
Indicates that the resource requested by a client does not exist, i.e., the URI is not valid. For example, when a GET request is performed on the following URI to retrieve a map resource named World Map: http://<server>:<port>/iserver/services/{component}/rest/maps/World Map.json Response code 200 is returned if everything is normal, indicating that the resource has been successfully retrieved. But if there is no map resource named World Map on the server, response code 404 will be returned, indicating that the resource is not valid. |
| 405 |
Indicates that the resource does not support this operation. For example, performing a PUT or DELETE request on a maps resource will get response code 405, indicating that the maps resource does not support PUT or DELETE. |
| 406 |
Indicates that the resource does not support the output format requested by the client (see Introduction to the output formats of SuperMap iServer REST API). For example, suppose a GET request is performed on the following URI to retrieve the maps resource: http://<server>:<port>/iserver/services/{component}/rest/maps.bmp Because maps is not an image resource, it does not support the BMP output format. Thus response code 406 is returned here. |
| 500 | Indicates that the request is not finished due to an unexpected situation on the server. |
After responding to a client's HTTP request, a REST service usually returns the client a representation in various formats. If the client performs a GET request, the resource will return the representation of that resource; if the client performs a PUT, POST, or DELETE request, the resource will return the representation of the operation result. REST resources support a number of output formats for representation, 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.
The output format is specified in the URI corresponding to the HTTP request, through adding .<format> to the end of the URI. For example, if a GET request is performed on http://<server>:<port>/iserver/services/{component}/rest/maps.json, the representation of the maps resource in json format will be returned. If no <format> is specified, a default format will be used for returning the representation. For a GET request, the default format of returned representation is html; for PUT, POST, and DELETE requests, the default format is rjson.
When it comes to image resources, a resource usually returns an image format (e.g., png) requested by the client. If an error occurs when the resource handles the request, and the image cannot be generated properly, an error message will be returned in json format. Note: If a REST service is operating under the Debug mode (the debug field of the REST configuration item in AppContext.xml is true), the error message will be in html format.
Below are the common output formats used in REST resources.
HTML is the default output format for non-image resources. An HTML page is returned. HTML can easily represent a table, and use a standard class to represent the table type.
For example, the following URI can be used to retrieve the HTML representation of the maps service:
http://<server>:<port>/iserver/services/{component}/rest /maps.html
Because html is the default output format for non-image resources, it does not have to be specified here, as shown in the following URI:
http://<server>:<port>/iserver/services/{component}/rest/maps
Enter the following URI: http://localhost:8090/iserver/services/maps/rest/maps.html，
The returned representation is shown in Figure 3:
Figure 3 The HTML representation
An xml file is returned. A series of XML terms are defined in SuperMap iServer to represent resources more correctly.
For example, the following URI can be used to retrieve the XML representation of the maps service:
http://<server>:<port>/iserver/services/{component}/rest/maps.xml
Below is an example of returned representation:
<?xml version="1.0" encoding="UTF-8"?><list>
<ChildResource>
<name>World Map</name>
<resourceType>StaticResource</resourceType>
<path>http://localhost:8090/iserver/services/components-rest/rest/maps/World Map.xml</path>
<supportedMediaTypes>
<string>application/xml</string>
<string>text/xml</string>
<string>application/json</string>
<string>application/rjson</string>
<string>text/html</string>
</supportedMediaTypes>
</ChildResource>
</list>
A JSON string is returned. JSON (JavaScript Object Notation) is a notation for JavaScript objects. It is a lightweight data interchange format, and can represent ordinary data structures.
For example, the following URI can be used to retrieve the JSON representation of the maps resource:
http://<server>:<port>/iserver/services/{component}/rest/maps.json
Below is an example of returned representation:
[{"resourceConfigID":null, "name":"World", "path":"http://localhost:8090/iserver/services/components-rest/rest/maps/World Map.json", "supportedMediaTypes":["application/xml", "text/xml", "application/json", "application/rjson", "text/html"], "resourceType":"StaticResource"}]
JSON is the default output format for PUT, POST, DELETE, and HEAD requests. Returned is a formatted JSON string that is easier to read.
For example, the following URI can be used to retrieve the RJSON representation of the maps resource:
http://<server>:<port>/iserver/services/{component}/rest/maps.rjson
Below is an example of returned representation:
[{
"name": "World Map",
"path": "http://localhost:8090/iserver/services/components-rest/rest/maps/World Map.rjson",
"resourceConfigID": null,
"resourceType": "StaticResource",
"supportedMediaTypes": [
"application/xml",
"text/xml",
"application/json",
"application/rjson",
"text/html"
]
}]
jsonp
JSONP (JSON with Padding) is a supplemental format to the JSON format, designed for clients to achieve cross-domain access.
For example, the following URI can be used to retrieve the JSONP representation of the maps resource, with the name of the callback function specified as mycallbackname:
http://supermapiserver:8090/iserver/services/components-rest/rest/maps.jsonp?callback=mycallbackname
Below is an example of returned representation:
mycallbackname([{
"resourceConfigID": null,
"name": "World",
"path": "http://supermapiserver:8090/iserver/services/components-rest/rest/maps/World",
"supportedMediaTypes": ["application/xml", "text/xml", "application/json", "application/rjson", "text/html", "application/jsonp", "application/ajax", "application/silverlight"],
"resourceType": "StaticResource"
}])
Figure 4 The PNG representation
A BMP image is returned by request. Valid only when the resource is an image resource.
For example, the following URI can be used to retrieve the current display of a map named World Map, in BMP format:
http://<server>:<port>/iserver/services/{component}/rest/maps/World Map/image.bmp
The returned result is an image in bmp format.
A GIF image is returned by request. Valid only when the resource is an image resource.
For example, the following URI can be used to retrieve the current display of a map named World Map, in GIF format:
http://<server>:<port>/iserver/services/{component}/rest/maps/World Map/image.gif
The returned result is an image in gif format.
A JPG image is returned by request. Valid only when the resource is an image resource.
For example, the following URI can be used to retrieve the current display of a map named World Map, in JPG format:
http://<server>:<port>/iserver/services/{component}/rest/maps/World Map/image.jpg
The returned result is an image in jpg format.
A JPEG image is returned by request. Valid only when the resource is an image resource.
For example, the following URI can be used to retrieve the current display of a map named World Map, in JPEG format:
http://<server>:<port>/iserver/services/{component}/rest/maps/World Map/image.jpeg
The returned result is an image in jpeg format.