Skip to content

REST API

Jump to bottom Edit New page
Emanuele Tajariol edited this page Jan 11, 2017 · 2 revisions

GeoFence REST API

Important

This page is work in progress. Formatting has to be completed. Please refer to this google doc .

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;
    • path parameter: 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 parameters 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
the IP address or name of your webapp server
port
the port of the webapp
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:

    • Content: 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 wkspace 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
Add a custom footer
Clone this wiki locally