Skip to content

GeoFence REST API

Jump to bottom Edit New page
Simone Giannecchini edited this page Sep 18, 2015 · 3 revisions

This document describes an HTTP REST API for CRUD operations in GeoFence DB.

Some insights on the internal model and rule evaluation procedures are also provided.

Here below we start with the description of some basic concepts in GeoFence.

GSUser

GSUsers (GeoServer users) are the basic authentication entities that make requests to GeoServer. They are internally identified by a system generated id, and may be externally identified by their name.

These are the main fields:

  • id (long): system id

  • name (string): user name as passed by geoserver

  • admin (bool): tells if the user is an admin; an admin has complete access to all resources with no need of further authorization requests

  • enabled(bool): tells if the user is currently enabled. If it is not, it will be treated as a guest user, and only default rules will apply.

UserGroup

A UserGroup is a grouping of GSUsers. GeoServer has no concept of this kind of group; it is only used at GeoFence level to express authorization rules for a group of users at once.

A user may belong to zero or more groups.

This concept was also known as "profile" in GeoRepository, but has changed name in UserGroup for sake of clarity.

These are the main fields:

  • id (long): system id

  • name (string): usergroup name, defined by the GeoFence admin

  • enabled(bool): tells if the group is currently enabled. Rules bound to disabled groups will not apply.

Instance

Instance is a GeoServer instance (or a cluster of instances). An instance has a name; when a GeoServer ask for an authorization, the call also include a "source geoserver name" to identify the caller, and working only on rules related to the given GeoServer instance.

You need to define the URL and the login credentials for the GeoServer instance in order for GeoFence to be able to ask the server some information (such as the list of workspaces, the list of layers, the attributes in a layer,...) when compiling the rules.

As mentioned above, note that clustered GeoServer instances should share the same name, in order to work on the same set of rules.

Rule

A Rule is a single authorization "atom".

A Rule is defined by a priority value, a match (that is, a set of fields that tells when such rule applies), an action, and optional constraints.

Priority

The priority is a positive integer number. When the authorization engine selects the matching rules, the resulting rule list is sorted by priority. The lower the priority number, the highest the priority. Usually the first matching rule is the one that "wins" and determines the final result.

Match

When GeoServer asks for an authorization, a filter is passed within the request. The filter specifies who made the request, and what is the object of the request. Such filter will be matched against the match.

Please note that any one of the match fields may be or may be not defined in a rule. In that latter case, the rule will match any value in the request. E.g.: a GeoServer filter with user "UserXYZ" will match any rule with "UserXYZ" set as user, and any rule with no user set (usually shown as a "*" in the GUI, meaning that any user will match that rule)

  • user The requesting user. It refers to a GSUser in the GeoFence DB.

  • group The group the requesting user belongs to. It refers to a UserGroup in the GeoFence DB.

  • instance The GeoServer instance the authorization request comes from. It refers to an Instance in the GeoFence DB.

  • service The OGC service for which the authorization request is queried. A String.

  • request The OGC request for which the authorization request is queried. A String.

  • workspace The workspace of the requested resource. A String.

  • layer The requested layer. A String.

Action

The Action specifies the outcome of the rule, if matched (by the filter) and selected (according to priority).

The two main actions are ALLOW and DENY. If one of these actions is encountered, the outcome is straightforward.

There's also the LIMIT action. Limiting rules add area constraints to the final outcome, if it's an ALLOW action.

In order to make it clearer, here is a skeleton of the rule selection mechanism:

  1. Given a filter, read all matching rules;

  2. Reading the rules in the proper priority order, check:

  3. if the action is limit, collect the constraints in this rule and go on examining the next rule

  4. if the action is deny, the request is not authorized.

  5. if the action is allow, the request is authorized, but the collected constraints, if any, shall be applied.

Constraints

Constraints on the resource can be added only in ALLOWing rules, and only when a layer is explicitly set in the match.

There are different kinds of constraints, and one ore more of them can be specified.

  • allowed area an optional multipolygon constraints. It may be used wherever it applies: e.g.: getMap requests will be cropped, and only the graphical part internal to the multipolygon will be drawn. getFeatures will only return features that are internal or intersect with the restriction multipolygon.

  • attribute access only used in vector layers. For every attribute, the rule may assign the accessibility level: non accessible, read only, full read/write access.

  • cql_filter_read, cql_filter_write these two constraints define cql filters to limit the set of features that can be read or written.

  • available_styles restrict the list of available styles for the layer filtered in the current rule. It may be useful to remove the styles that use one or more inaccessible attributes.

  • default_style override the default style for the the layer filtered in the current rule.

Some notes

There is no explicit concept of user role here. We'll deal with only one kind of role here, apart from the normal USER role, and that's the ADMIN. An ADMIN in GeoServer has access to everything; this means that, once authenticated as ADMIN, no further authorization requests will be made by GeoServer toward GeoFence. The admin role is implemented as a boolean flag in GSUser.

Rule engine

Authorization requests

When GeoServer receives a resource request, it needs various authorization info, from the most general ones (e.g.: is a given service available at all?), to the most specific ones (e.g. is a given layer in a given workspace available to a given user?). A bridge class will translate this geoserver-specific authorization request into a GeoFence rule filter, will send this filter to GeoFence and will then translate the response back into the Geoserver model.

Note that a single request to GeoServer may result in more than one auth request from GeoServer to GeoFence.

Applying rules

User belonging to a single group

When a rule filter arrives, its fields are checked against the Rules’ match fields. The selected rules are then examined sorted by priority, and the first matching DENY/ALLOW rule applies.

User belonging to multiple groups

GeoServer will never send a filtering on groups, so group handling is entirely performed by GeoFence.

When a user belongs to more than one group, the entire "single group" procedure is repeated for each group the user belongs to: a filter is created using the provided input user and one of the groups, leaving the other filtering fields (instance, service, layer, ...) unaltered, and the outcome is computed with the aforementioned procedure. We’ll have one outcome for every group the user belongs to. All of these results will be merged into one, selecting the most permissive constraints:

  • CQL filters will be put in logical OR; as a special case, if one of the CQL filters is not present, there will be no CQL filtering;

  • restricted areas will be UNIONed

  • the sets of allowed styles will be merged

  • the set of attributes will be merged, taking the most permissive grant on every attribute (e.g.: if attr1 is "NONE" for one group, and “READONLY” for another group, the output grant for that attribute will be “READONLY”)

  • if at least one of the defaultStyle is null, the output defaultStyle will be null, otherwise one random defaultStyle from the various responses will be chosen.

REST operations

For every service, the service base path will be given.

For every operation, there will be details about:

  • the HTTP method needed (GET, POST, PUT, DELETE)

  • the path

  • the list of params used;

    • if no further indication is given, the parameter is a path parameter, that is a value that is part of the URL path; e.g. in /users/id/{*id*}, {id} is a path parameter, and an instance may be /users/id/100

    • *Query parameter *are usually optional. They are explicitly denoted, such as in "Query param: cascade: when “true", also removes all Rules referring to given user.”. They are appended at the end of the URL, separated from the base URL using a “?” character and separated each other by a “&” char. e.g. /users/id/100?cascade=true

    • Payload: complex data transferred in the message body of the request.

The full URL is built that way

http://server_name:port/web_app_name/rest_servlet/service_base_path/operation_path

  • server_name and port: the IP address or name of your webapp server

  • web_app_name: the webapp name, usually geofence (or georepo for previous versions)

  • rest_servlet: string mapped in web.xml, is by default set to "rest"

  • service_base_path: each of next services will have its own; e.g. "users" or “rules”

  • operation_path: each described operation will have its own.

GSUsers operations

CRUD operations on GSUsers.

Service base path: /users

Insert

Inserts a new user into the DB.

  • HTTP method: POST

  • Path: /

  • Params:

    • Payload: GSUser data encoded as text/xml: these are the available fields:

      • enabled: see GSUser definition in glossary

      • admin: see GSUser definition in glossary

      • name: the username used when requesting resources to GeoServer

      • password: only used when there is an authentication mechanism in place that uses GeoFence DB as backend. May be left blank.

      • fullname: only descriptive, may be left blank.

      • emailAddress: may be left blank; not used directly by geofence.

      • extId: an external identifier to assign to the user. It’s nullable; if defined, it should be unique. Only informative, not used by GeoFence.

      • groups: the list of the userGroups the user belongs to. A group may be identified either by id or by name.

    • e.g.:

<user enabled="true" admin="false">
    <extId>ext_02</extId>
    <name>name_02</name>
    <password>pw_02</password>
    <fullName>fullname_02</fullName>
    <emailAddress>email_02</emailAddress>
    <groups>
        <group>
            <id>1538</id>
        </group>
        <group>
            <name>grp_02</name>
        </group>
    </groups>
</user>

  • Response: the id of the new user, as a long integer in plain text

  • ETag: the id of the new user

  • HTTP return codes

    • 201 created: ok

    • 400 bad request: error in the input data

    • 404: one of the the requested groups has not be found.

    • 409 conflict: a user with the given name already exists

    • 500: generic internal error

Update

Updates info for an existing GSUser.

  • HTTP method: PUT

  • Path: either

    • /id/{*userId*}

    • /name/{*userName*}

  • Params:

    • userId: the id of the user in the DB

    • userName: the name of the user in the DB

    • Payload: GSUser, encoded as text/xml. Refer to the Insert operation for the GSUser encoding. Only the fields that should be updated should be set in the payload. Note that some fields may not be updated, namely:

      • extId

      • name

  • HTTP return codes

    • 200: ok

    • 400 bad request: error in the input data

    • 404: the user or one of the the requested groups has not been found.

    • 500: generic internal error

Delete

  • HTTP method: DELETE

  • Path: either

    • /id/{*userId*}

    • /name/{*userName*}

  • Params:

    • userId: the id of the user in the DB

    • userName: the name of the user in the DB

    • Query param: cascade: when "true", also removes all Rules referring to given user.

  • HTTP return codes

    • 200: ok

    • 404: user not found

    • 409 conflict: user is referenced in a rule (should not be returned when cascade="true”)

    • 500: generic internal error

Retrieve list

Returns an (optionally) paginated list of users. See also the count operation.

  • HTTP method: GET

  • Path: /

  • Optional query params:

    • nameLike An optional LIKE filter on the username.

    • page In a paginated list, the page number, 0-based. If not null, entries must be defined as well.

    • entries* *In a paginated list, the number of entries per page. If not null, page must be defined as well.

  • Response: a list of basic data about existing users, as text/xml

    • e.g.
   <UserList>
       <User enabled="true">
         <id>537</id>
          <extId>ext_01</extId>
          <userName>user_01</userName>
       </User>
       <User enabled="true">
          <id>538</id>
          <extId>ext_02</extId>
          <userName>user_02</userName>
       </User>
    </UserList>

  • HTTP return codes

    • 200: ok

    • 500: generic internal error

Count

Returns the (optionally) filtered count of users.

  • HTTP method: GET

  • Path: /count

  • Optional query params:

    • nameLike An optional LIKE filter on the username.

  • Response: the number of users matching the filter, as integer in text/plain

  • HTTP return codes

    • 200: OK

    • 500: generic internal error

Retrieve single

Returns detailed info on a single user.

  • HTTP method: GET

  • Path: either

    • /id/{*userId*}

    • /name/{*userName*}

  • Response: the GSUser details, as text/xml. Refer to the Insert operation for the GSUser encoding. You may not get some fields, such as the password.

  • HTTP return codes

    • 200: OK

    • 404: no user found with such id or name

    • 500: generic internal error

Assign to UserGroup

Adds a user into a userGroup

  • HTTP method: PUT

  • Path: one in

    • /id/{*userId*}/group/id/{*id*}

    • /id/{*userId*}/group/name/{*groupName*}

    • /name/{*userName*}/group/id/{*id*}

    • /name/{*userName*}/group/name/{*groupName*}

  • HTTP return codes

    • 200: OK

    • 404: no user or group found with such id or name

    • 500: generic internal error

Remove from UserGroup

Remove a user from userGroup

  • HTTP method: DELETE

  • Path: one in

    • /id/{*userId*}/group/id/{*id*}

    • /id/{*userId*}/group/name/{*groupName*}

    • /name/{*userName*}/group/id/{*id*}

    • /name/{*userName*}/group/name/{*groupName*}

  • HTTP return codes

    • 200: OK

    • 404: no user found with such id or name

    • 500: generic internal error

Groups operations

CRUD operations on user groups.

Service base path: /groups

Insert

Inserts a new usergroup into the DB.

  • HTTP method: POST

  • Path: /

  • Params:

    • Payload: UserGroup data encoded as text/xml: these are the available fields:

      • enabled: see Group definition in glossary

      • name: the group name

      • extId: an external identifier to assign to the user. It’s nullable; if defined, it should be unique. Only informative, not used by GeoFence.

    • e.g.:

   <userGroup enabled="true">
       <extId>external_id_here</extId>
	   <name>sample group</name>
   </userGroup>

  • Response: the id of the new group, as a long integer in plain text

  • ETag: the id of the new group

  • HTTP return codes

    • 201 created: ok

    • 400 bad request: error in the input data

    • 409 conflict: a group with the given name already exists

    • 500: generic internal error

Update

Updates info for an existing usergroup.

  • HTTP method: PUT

  • Path: either

    • /id/{groupId}

    • /name/{groupName}

  • Params:

    • groupId: the id of the group in the DB

    • groupName: the name of the group in the DB

    • Payload: UserGroup, encoded as text/xml. Refer to the Insert operation for the UserGroup encoding. Only the fields that should be updated should be set in the payload. Note that some fields may not be updated, namely:

      • extId

      • name

  • HTTP return codes

    • 200: ok

    • 400 bad request: error in the input data

    • 404: the group has not been found

    • 500: generic internal error

Delete

  • HTTP method: DELETE

  • Path: either

    • /id/{groupId}

    • /name/{groupName}

  • Params:

    • groupId: the id of the group in the DB

    • groupName: the name of the group in the DB

    • Query param: cascade: when "true", also removes all Rules referring to given group.

  • HTTP return codes

    • 200: ok

    • 404: group not found

    • 409 conflict: group is referenced in a rule (should not be returned when cascade="true”)

    • 500: generic internal error

Retrieve list

Returns an (optionally) paginated list of groups. See also the count operation.

  • HTTP method: GET

  • Path: /

  • Optional query params:

    • nameLike An optional LIKE filter on the group name.

    • page In a paginated list, the page number, 0-based. If not null, entries must be defined as well.

    • entries* *In a paginated list, the number of entries per page. If not null, page must be defined as well.

  • Response: a list of basic data about existing groups, as text/xml

    • e.g.
<UserGroupList>

   <UserGroup enabled="true">

      <id>-1237460590</id>

      <extId>ext_group1</extId>

      <name>group1</name>

      <dateCreation>2012-06-13T13:21:31.940+02:00</dateCreation>

   </UserGroup>

   <UserGroup enabled="true">

      <id>-1237460589</id>

      <extId>ext_group2</extId>

      <name>group2</name>

      <dateCreation>2012-06-13T13:21:31.940+02:00</dateCreation>

   </UserGroup>

</UserGroupList>

  • HTTP return codes

    • 200: ok

    • 500: generic internal error

Count

Returns the (optionally) filtered count of groups.

  • HTTP method: GET

  • Path: /count

  • Optional query params:

    • nameLike An optional LIKE filter on the group name.

  • Response: the number of groups matching the filter, as integer in text/plain

  • HTTP return codes

    • 200: OK

    • 500: generic internal error

Retrieve single

Returns detailed info on a single group.

  • HTTP method: GET

  • Path: either

    • /id/{groupId}

    • /name/{groupName}

  • Params:

    • groupId: the id of the group in the DB

    • groupName: the name of the group in the DB

  • Response: the UserGroup details, as text/xml. Refer to the Insert operation for the Group encoding.

  • HTTP return codes

    • 200: OK

    • 404: no group found with such id or name

    • 500: generic internal error

GSInstances operations

CRUD operations on stored GeoServer instances.

Service base path: /instances

Insert

Inserts a new instance into the DB.

  • HTTP method: POST

  • Path: /

  • Params:

    • Payload: GSInstance data encoded as text/xml: these are the available fields:

      • name: the instance name

      • description: human readable description of the site.

      • baseURL: geoserver full URL, see example

      • username: geoserver admin username

      • password: geoserver admin password

    • e.g.:

<instance>
   <name>sample instance</name>
   <description>sample descr</description>
   <baseURL>http://yourgeoserver/geoserver</baseURL>
   <username>admin</username>
   <password>clearpw</password>
</instance>

  • Response: the id of the new instance, as a long integer in plain text

  • ETag: the id of the new instance

  • HTTP return codes

    • 201 created: ok

    • 400 bad request: error in the input data

    • 409 conflict: an instance with the given name already exists

    • 500: generic internal error

Update

Updates info for an existing instance.

  • HTTP method: PUT

  • Path: either

    • /id/{instanceId}

    • /name/{instanceName}

  • Params:

    • instanceId: the id of the instance in the DB

    • instanceName: the name of the instance in the DB

    • Payload: GSInstance, encoded as text/xml. Refer to the Insert operation for the GSInstance encoding. Only the fields that should be updated should be set in the payload. Note that some fields may not be updated, namely:

      • name

  • HTTP return codes

    • 200: ok

    • 400 bad request: error in the input data

    • 404: the instance has not been found

    • 500: generic internal error

Delete

  • HTTP method: DELETE

  • Path: either

    • /id/{instanceId}

    • /name/{instanceName}

  • Params:

    • instanceId: the id of the instance in the DB

    • instanceName: the name of the instance in the DB

    • Query param: cascade: when "true", also removes all Rules referring to given instance.

  • HTTP return codes

    • 200: ok

    • 404: instance not found

    • 409 conflict: instance is referenced in a rule (should not be returned when cascade="true”)

    • 500: generic internal error

Retrieve list

Returns an (optionally) paginated list of instances. See also the count operation.

  • HTTP method: GET

  • Path: /

  • Optional query params:

    • nameLike An optional LIKE filter on the group name.

    • page In a paginated list, the page number, 0-based. If not null, entries must be defined as well.

    • entries* *In a paginated list, the number of entries per page. If not null, page must be defined as well.

  • Response: a list of basic data about existing instances, as text/xml

    • e.g.
<GSInstanceList>

   <Instance>

      <id>100</id>

      <name>instance_01</name>

      <url>http://test/geoserver</url>

   </Instance>

   <Instance>

      <id>101</id>

      <name>instance_02</name>

      <url>http://othertest/geoserver</url>

   </Instance>

</GSInstanceList>

  • HTTP return codes

    • 200: ok

    • 500: generic internal error

Count

Returns the (optionally) filtered count of instances.

  • HTTP method: GET

  • Path: /count

  • Optional query params:

    • nameLike An optional LIKE filter on the instance name.

  • Response: the number of instances matching the filter, as integer in text/plain

  • HTTP return codes

    • 200: OK

    • 500: generic internal error

Retrieve single

Returns detailed info on a single instance.

  • HTTP method: GET

  • Path: either

    • /id/{instanceId}

    • /name/{instanceName}

  • Params:

    • instanceId: the id of the instance in the DB

    • instanceName: the name of the instance in the DB

  • Response: the GSInstance details, as text/xml. Refer to the Insert operation for the GSInstance encoding.

  • HTTP return codes

    • 200: OK

    • 404: no instance found with such id or name

    • 500: generic internal error

Rules operations

CRUD operations on GeoFence rules.

Service base path: /rules

Insert

Inserts a new rule into the DB.

  • HTTP method: POST

  • Path: /

  • Params:

    • Payload: Rule data encoded as text/xml: most of the fields are explained in the glossary. Here some tech specs:

      • grant may be ALLOW, DENY, LIMIT

      • position/@position may be:

        • fixedPriority: a fixed priority number. If a Rule already exists with the same priority value, all existing rules with priority >= value will have their priority incremented by 1.

        • offsetFromTop: integer offset: rule will be added as fromTopth rule from the top, following the ordering by priority value (lowest value is higher priority). E.g. offsetFromTop=0 will create a top-priority rule.

        • offsetFromBottom: similar to fromTop, the rule will be added at the lowest priority, skipping the last fromBottom ones. E.g.:If you already have a catchall rule in last position, you may want to add your new rule as offsetFromBottom=1;

      • attributes/attribute/@access may be: NONE, READONLY, READWRITE

      • user, group and instance may be referred either by id or by name

      • constraints can be defined only if the layer field is not null

      • constraints/type: allowed values are VECTOR or RASTER. It must reflect GS real layer type; it’s needed for internal checks.

      • e.g.:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rule grant="ALLOW">
    <position value="1" position="offsetFromBottom"/>
    <user>
        <name>user_02</name>
    </user>
    <group>
        <name>grp_02</name>
    </group>
    <instance>
        <id>1538</id>
    </instance>
    <service>WMS_02</service>
    <request>getMap_02</request>
    <workspace>wsp_02</workspace>
    <layer>layer_02</layer>
    <constraints>
        <type>VECTOR</type>
        <defaultStyle>Style_02</defaultStyle>
        <cqlFilterRead>CQL_READ_SAMPLE</cqlFilterRead>
        <cqlFilterWrite>CQL_WRITE_SAMPLE</cqlFilterWrite>
        <restrictedAreaWkt>wkt_02</restrictedAreaWkt>
        <allowedStyles>
            <style>teststyle2</style>
            <style>teststyle1</style>
            <style>Style_02</style>
        </allowedStyles>
        <attributes>
            <attribute access="NONE">
                <datatype>java.lang.String</datatype>
                <name>attr1</name>
            </attribute>
            <attribute access="READONLY">
                <datatype>java.lang.String</datatype>
                <name>attr2</name>
            </attribute>
            <attribute access="READWRITE">
                <datatype>java.lang.String</datatype>
                <name>attr3</name>
            </attribute>
        </attributes>
    </constraints>
</rule>

  • Response: the id of the new rule, as a long integer in plain text

  • HTTP return codes

    • 201: created

    • 404: user, group or instance not found.

    • 500: generic internal error

Update

Updates info for an existing Rule.

  • HTTP method: PUT

  • Path:

    • /id/{*ruleId*}

  • Params:

    • ruleId: the id of the rule in the DB

    • Payload: Rule data encoded as text/xml. Refer to the Insert operation for the Rule encoding. Note that some fields may not be updated:

      • grant

      • position

  • HTTP return codes

    • 200: ok

    • 404: rule, user, group or instance not found.

    • 500: generic internal error

Delete

  • HTTP method: DELETE

  • Path:

    • /id/{*ruleId*}

  • Params:

    • ruleId: the id of the rule in the DB

  • HTTP return codes

    • 200: ok

    • 404: rule not found.

    • 500: generic internal error

Retrieve list

Returns a list of rules.

The list may optionally be filtered and paginated. For the paginated output, you may also be interested in the count operation.

Filtering is performed using optional query parameters. You may filter on any field in the match set.

Constraints for entities defined in GeoFence (users, groups, instances) may be defined either using the entity id or the entity name. Constraints on free text match fields are only expressed by a filter on the exact string (service, request, workspace, layer). All these kind of filters are put in logical AND; it means that if you define userName=u01&layer=l02 you’ll get only the rules referring to such user and layer.

When defining a filter on a field, you may also want to get the rules where such field is not defined at all (rules that will apply when an authorization check is performed); you can do it by using the related *Any parameter: e.g. userName=u01&userAny=true will return all the rules associated to the user "u01" and all the rules with no user associated.

If you use an Any parameter with no filter associated to that field, you’ll get only the rules with the default value () in that field.

Some examples:

  • no filters in the service field there will be no filtering in the service field

  • service=WMS only rules with WMS service will be returned

  • serviceAny=true only rules with service="*” will be returned

  • service=WMS&serviceAny=true rules with service=WMS and rules with service="*” will be returned

  • HTTP method: GET

  • Path: /

  • Optional query params:

    • userName: filter

    • userId: filter

    • userAny: extend the filter to also include rules with no user defined

    • groupName: filter

    • groupId: filter

    • groupAny: extend the filter to also include rules with no group defined

    • instanceName: filter

    • instanceId: filter

    • instanceAny: extend the filter to also include rules with no instance defined

    • service: filter

    • serviceAny: extend the filter to also include rules with no service defined

    • request: filter

    • requestAny: extend the filter to also include rules with no request defined

    • workspace: filter

    • workspaceAny: extend the filter to also include rules with no workspace defined

    • layer: filter

    • layerAny: extend the filter to also include rules with no layer defined

    • page: In a paginated list, the page number, 0-based. If not null, entries must be defined as well.

    • entries:* *In a paginated list, the number of entries per page. If not null, page must be defined as well.

    • full: boolean: if "true", also include the layer constraints in the response

  • Response: a list of filtered rules, as text/xml. For nested internal entities (users, groups, instances), both id and name will be provided.

    • e.g.
<RuleList>
    <Rule grant="ALLOW">
        <id>1000</id>
        <priority>100</priority>
        <user>
            <id>7229</id>
            <name>user_01</name>
        </user>
        <group>
            <id>5679</id>
            <name>grp_01</name>
        </group>
        <instance>
            <id>3415</id>
            <name>gs_01</name>
        </instance>
        <service>WMS_01</service>
        <request>getMap_01</request>
        <workspace>wsp_01</workspace>
        <layer>layer_01</layer>
    </Rule>
    <Rule grant="DENY">
        <id>1001</id>
        <priority>101</priority>
        <group>
            <id>2062</id>
            <name>grp_02</name>
        </group>
        <instance>
            <id>2382</id>
            <name>gs_02</name>
        </instance>
        <service>WMS</service>
        <workspace>wsp_02</workspace>
        <layer>layer_02</layer>
    </Rule>
</RuleList>

  • HTTP return codes

    • 200: ok

    • 400 bad request: error in the param combination

    • 500: generic internal error

Count

Returns the (optionally) filtered count of rules.

  • HTTP method: GET

  • Path: /count

  • Optional query params:

    • all of the filtering params descripted in the "retrieve list" operation apply.

  • Response: the number of rules matching the filter, as integer in text/plain

  • HTTP return codes

    • 200: OK

    • 500: generic internal error

Batch operations

This operation will perform multiple insert/update/remove operations in a single transaction.

Path: /batch/exec

HTTP method: POST

Payload: an XML Document, here called BatchDocument

BatchDocument

BatchDocument is an XML document with a root element <batch>.

The root element may contain 0..n of the operation elements, in any order, that specify the operations that should be performed on the data base.

The operations on the DB will be executed following the same ordering of the operation list given in input.

Any error in any operation will fail the entire batch, and the transaction will be rolled back.

Operation elements’ technical rationale

The operation elements resemble the related calls in unwrapped REST services.

Parameters in the URL path will be set as attributes in the operation element. The payload will be set as the content of the operation element.

For instance, an "update user" operation, in the unwrapped service, is performed using a

PUT in the URL /users/id/{userId}, putting the users details in the payload "XXX".

The equivalent operation element will be

<operation type="update” service=”users” id=”userId”>*XXX*</operation>

The error conditions that will make the batch stop and rollback are the same ones detailed in the standalone REST operations.

Operation elements list

Delete operations

For users, groups and instances this operation element can be used:

  • <operation type="delete” service=”*SERVICE*” *IDENTIFIER*/>

  • SERVICE may be "users", “groups” or “instances”.

  • IDENTIFIER may be either:

    • id="id”

    • name="objectName”

  • BOOL may be either "true" or “false”

  • Optional attributes:

    • cascade: boolean; when true, also deletes referring Rules.

For rules, this operation element shall be used:

  • <operation type="delete” service=”rules” id=”*ID*”/>

where ID is the id of the rule that shall be deleted.

Insert operations

All insert operation elements are in the format:

  • <operation type="insert” service=”*SERVICE*”> *XML_CONTENT* </operation>

  • SERVICE should be one in "users", “groups”, “instances”, “rules”.

  • The operation element should have as child the XML_CONTENT that the related standalone operation would have; it means that the operation element for the creation of a user would be something like:

    **<operation type="insert” service=”****_users_****”>**

<user enabled="true">
    <extId>ext_02</extId>
    <name>name_02</name>
    <password>pw_02</password>
    <fullName>fullname_02</fullName>
    <emailAddress>email_02</emailAddress>
    <restrictedAreaWkt>MULTIPOLYGON_02</restrictedAreaWkt>
    <groups>
        <group>
            <id>1538</id>
        </group>
        <group>
            <name>grp_02</name>
        </group>
    </groups>
</user>

**    </operation>**

Update operations

All update operation elements are in the format:

<operation type="update” service=”*SERVICE*” *IDENTIFIER*>

    *XML_CONTENT*

</operation>

  • SERVICE should be one in "users", “groups”, “instances”, “rules”.

  • IDENTIFIER may be either:

    • id="id”

    • name="objectName” (not allowed for rules)

  • The operation element should have as child the XML_CONTENT that the related standalone operation would have.

Group association

  • <operation type="addGroup” service=”users” *USERIDENTIFICATION GROUPIDENTIFICATION*/> Adds a user in a userGroup.

    • Attributes:

      • USERIDENTIFICATION: (mandatory) either userId or userName

      • GROUPIDENTIFICATION: (mandatory) either groupId or groupName

  • <operation type="delGroup” service=”users” *USERIDENTIFICATION GROUPIDENTIFICATION*/> Removes a user from a userGroup.

    • Attributes:

      • USERIDENTIFICATION: (mandatory) either userId or userName

      • GROUPIDENTIFICATION: (mandatory) either groupId or groupName

Config operations

Configuration operation, such as backup and restore.

Service base path: /config

Backup

Retrieve an XML document containing a backup of GeoFence data.

The returned document is a Batch document containing insert operation for each object in the GeoFence database.

Administrator accounts will not be inserted into the returned document.

  • HTTP method: GET

  • Path: /backup

  • Params: none

  • Response: a Batch document, as text/xml.

You may also have a backup copy of a single type of object: these are the paths, with obvious meaning:

  • /backup/groups

  • /backup/users

  • /backup/instances

  • /backup/rules

Notice that the backup of a single type may be of little use in restoring, since most of the objects will reference to other object types (e.g., a user will refer to usergroups).

Restore

Restore data from a batch document.

The restore operation will delete any existing info (except administrator accounts), and will then process the provided batch document. The batch document is not processed transactionally, so any error will leave the DB with only the entries inserted until the error is triggered.

The CreationDate field will not be preserved, and will be recreated.

  • HTTP method: PUT

  • Path: /restore

  • Params:

    • Payload: BatchDocument encoded as text/xml.

  • Response: a Batch document, as text/xml.

  • HTTP return codes

    • 200: ok

    • 400 bad request: error in the document

    • 404 not found: error in internal references

    • 500: generic internal error

Cleanup

Delete GeoFence data.

This operation will delete any existing UserGroup, GSUser, Instance, and Rule. It will not remove administrator accounts.

  • HTTP method: PUT

  • Path: /cleanup

  • Params: none

  • HTTP return codes

    • 200: ok

    • 500: generic internal error

Add a custom footer
Clone this wiki locally