html.master.html Maven / Gradle / Ivy
Show all versions of geomajas-face-rest-documentation
Geomajas REST face guide Table of Contents
List of Tables
- 3.1. HTTP parameters
- 3.2. HTTP parameters
List of Examples
- 2.1. Plug-in dependency
The REST face provides access to the Geomajas server through a RESTful
protocol. The current implementation provides read-only access to the
various vector layers configured on the server. Our protocol implementation
was largely inspired by the Mapfish
protocol, which should be in line with - or at least supported by -
the OpenLayers client implementation. We also support clients of FeatureServer, which has a much more
limited parameterset. As far as we know, there is currently no REST standard
for feature services, although there is some consensus on the rest
principles (using uri extensions to determine the output format, exposing
single features as uris, etc...).
Table of Contents
The configuration of the REST plugin consists of a maven part and a
web MVC part.
Make sure your include the plug-in in your project. If you are using
Maven, add the following dependency to your pom:
Example 2.1. Plug-in dependency
<dependency>
<groupId>org.geomajas</groupId>
<artifactId>geomajas-face-rest</artifactId>
<version>1.18.2</version>
</dependency>
The web configuration is by default based on the bean name URL
handler mapping. This means that the name of the scanned controller beans
determines the URL base that points to the REST services. More
specifically, the RestController class (see below) has an annotation that
tells the DispatcherServlet to map all urls that start with
http://{host}:{port}/{context}/{dispatcher}/rest/ to the REST
service, where host, port and
context should be replaced with the host, port and web
context of your deployment and /{dispatcher}/* is the url
pattern of the DispatcherServlet mapping (as configured in
web.xml).
Warning
the current faces depend on the mapping of /d/* to
the DispatcherServlet !
@Controller("/rest/**")
public class RestController {
@RequestMapping(value = "/rest/{layerId}/{featureId}.json", method = RequestMethod.GET){
...
}
Further narrowing of the url mapping to class methods is done
through the RequestMapping annotations. For a thorough
explanation of the various url parameters we refer to the next chapter,
which explains the usage of the REST face as a client. Unless you
absolutely want to change the url path, there is no need to override the
default configuration. If you do want to change this, however, one
possibility is to add additional mappings by configuring a
SimpleUrlHandlerMapping bean, which allows mapping of arbitrary paths to
controller beans.
The REST plugin exposes a RESTful web interface towards compatible
clients. In this chapter we will give an overview of all available HTTP
operations and their respective parameters. The base uri for the REST
service is http://{host}:{port}/{context}/{dispatcher} where
/dispatcher}/* is the url mapping for the DispatcherServlet (as
configured in web.xml). We will refer to this as http://base.
Warning
the current faces depend on the mapping of /d/* to the
DispatcherServlet !
Although extensible to multiple response formats, the REST service is
currently limited to GeoJSON only. The GeoJSON specification can be found at
http://geojson.org/geojson-spec.html.
The method and request uri for reading a single feature is:
GET http://base/rest/{layerId}/{featureId}.{format}The
url parameters are:
-
layerId : the server layer id of the vector layer
-
featureId : the id of the feature
-
format : the format of the returned feature, possible values are: json, kml, shp, txt
If successful, the response is as follows:
-
200 OK
-
a single feature in GeoJSON, KML, shapefile or text format
If the feature does not exist, the response is as follows:
-
404 Not Found
If something else went wrong, the response is:
-
500 Internal server error
-
the error message of the RestException
The following parameters are supported:
Table 3.1. HTTP parameters
Name Value Description no_geom true|false if true, the returned feature has no geometry ("geometry":
null) attrs {field1}[,{field2},...] a list of attributes to restrict the list of properties
returned in the feature
The method and request uri for reading multiple features is:
GET http://base/rest/{layerId}The
url parameters are:
-
layerId : the server layer id of the vector layer
If successful, the response is as follows:
-
200 OK
-
a GeoJSON feature collection with 0 or more features
If the feature does not exist, the response is as follows:
-
404 Not Found
If something else went wrong, the response is:
-
500 Internal server error
-
the error message of the RestException
The following parameters are supported:
Table 3.2. HTTP parameters
Name Value Description no_geom true|false if true, the returned feature has no geometry ("geometry":
null) epsg {num} the EPSG code of the box value and the returned geometries format json|shp|txt|kml The format of the response, default is json attrs {field1}[,{field2},...] a list of attributes to restrict the list of properties
returned in the feature box | bbox {xmin,ymin,xmax,ymax} a list of coordinates representing a bounding box, the
coords' projection system can be specified with the epsg parameter
(bbox is an alias to box) maxFeatures | limit {num} limit the number of features to num features (maxfeatures
is an alias to limit) offset {num} skip num features order_by {field} order the features using field dir DESC|ASC determine the ordering direction (applies only if order_by
is specified) queryable {field1}[,{field2},...]} the names of the feature fields that can be used in the
field query parameters (see next row) {field}__{query_op} {value} specify a filter expression, field must be in the list of
fields specified by queryable, supported query_op's
are:-
eq: equal to
-
ne: not equal to
-
lt: lower than
-
lte: lower than or equal to
-
gt: greater than
-
gte: greater than or equal to
-
like: sql like for string values
The parameters lat, lon, tolerance have not yet been
implemented.
OpenLayers is the most
popular web mapping javascript library and supports the REST protocol for
feature access. To connect with an OpenLayers client, add the following
layer to your map:
var layer = new OpenLayers.Layer.Vector("GeoJSON", {
strategies: [new OpenLayers.Strategy.Fixed()],
protocol: new OpenLayers.Protocol.HTTP({
url: "http://base/rest/{layerId}", // replace with the actual url for your layer !
format: new OpenLayers.Format.GeoJSON()
})
});
An example web application with OpenLayers can be found in the
geomajas-face-rest-example project.