Skip to content

Latest commit

 

History

History
147 lines (114 loc) · 5.85 KB

README_expansion.md

File metadata and controls

147 lines (114 loc) · 5.85 KB
Raw

gateleen-expansion

Parameter: expand=x

Usage

http:///collection?expand=x

x can be a value from 1 to infinity. It represents the maximum recursion level and is limited by the following properties:

  • max.expansion.level.soft
  • max.expansion.level.hard
  • max.expansion.subrequests
max.expansion.level.soft

The max.expansion.level.soft property (default value = Integer.MAX_VALUE) defines a soft limit for the maximum expansion level. A soft limit means that the expand request will only be expanded to the max.expansion.level.soft value.

Example: max.expansion.level.soft is configured to value 3. When making the request

GET http://localhost:7012/gateleen/some_resources?expand=4

the data are only expanded until level 3. An additional warning will be logged, that the maximum expansion level has been exceeded.

max.expansion.level.hard

The max.expansion.level.hard property (default value = Integer.MAX_VALUE) defines the hard limit for the maximum expansion level. This means that expand requests with an expand parameter higher than max.expansion.level.hard value are responded with

400 Bad Request

max.expansion.subrequests

The expansion is also limited by the property max.expansion.subrequests which sets the maximum count of requests created by one recursive GET request.

The RecursiveExpansionHandler allows you to send GET requests to the server which are resolved recursively. What does that actually mean? Let’s have a look at an example:

GET http://localhost:7012/gateleen/some_resources

{
    "some_resources": [
            "v1/"
    ]
}

But what do I have to do, if I want to get all the sub-resources in the given resource tree? This problem is solved with the recursive GET feature:

GET http://localhost:7012/gateleen/some_resources?expand=4

{
    "some_resources": {
        "v1": {
            "control": {
                "activations": {
                    "2aa5bf9a-3d51-49c6-b1a0-9f053ac8815b": {
                        "timestamp": "2015-02-12T11:35:11.655+01:00",
                        ...
                    },
                    "41766497-07b8-47d5-967c-a03db2b99b8d": {
                        "timestamp": "2015-02-12T11:35:11.655+01:00",
                        ...
                    }
                }
            }
        }
    }
}

Expand 3 levels only:

GET http://localhost:7012/gateleen/some_resources?expand=3

{
    "some_resources": {
        "v1": {
            "control": {
                "activations": [
                    "2aa5bf9a-3d51-49c6-b1a0-9f053ac8815b",
                    "41766497-07b8-47d5-967c-a03db2b99b8d"
                ]
            }
        }
    }
}

Additional information:

Note:

  • Each request is created with a eTag header. A second request to the same resource will lead, if nothing changed, to a 304 "Not Modified" response.
  • If the given recursion depth (x) is higher than the depth of the tree, the depth of the tree will be used. So it is safe to use high level of x if you want to expand a complete tree, but are not sure how deep he really is.

Attention:

  • If the collection is not found, status code 404 "Not found" is returned.
  • If the collection actually is not a collection, 400 "Request did not return data. Invalid usage of params expand ?" is returned.
  • If the collection contains NON-Json Resources OR if a Json Resource is malformed, 500 "Errors found in resources:" with a list of the problematic resources is returned.
  • If the number of allowed sub requests exceeds the given limit, 400 "Number of allowed sub requests exceeded. Limit is x requests" is returned.

Expand on Backend

If you want that the backend expands the request and not gateleen, you can set the attribute:

expandOnBackend=true

in the corresponding routing rule.

StorageExpand

If you want to use the StorageExpand feature, you can set the attribute:

storageExpand=true

in the corresponding routing rule. The StorageExpand feature does expand directly in the storage, so it is faster than the "standard" expansion feature.

Attention: Be aware that the depth is limited to 1 by now, regardless of the max.expansion.level.hard value.

Attention: You must allow the POST method (in the acls) for the urls you want to use with the StorageExpand feature!

For more information about the StorageExpand feature see the vertx-rest-storage project.

Parameter: expand=x&zip=true

Usage

http:///collection?expand=x&zip=true

This allows you to create one octet-stream containing each json resource in the given collection (see expand feature). Basically it works exactly the same way as the default expand feature works, except that it does not set an eTag for the request.

Attention: No eTag header is created / returned when this feature is used!

Micrometer metrics

The expansion feature is monitored with micrometer. The following metrics are available:

  • gateleen_expand_requests_total
  • gateleen_storage_expand_requests_total

For expand_requests_total additional tags are provided to specify the expand level.

Example metrics:

# HELP gateleen_expand_requests_total  
# TYPE gateleen_expand_requests_total counter
gateleen_expand_requests_total{level="1",} 23677.0
gateleen_expand_requests_total{level="2",} 2350.0
gateleen_expand_requests_total{level="3",} 77.0
gateleen_expand_requests_total{level="4",} 0.0
gateleen_expand_requests_total{level="0",} 0.0
# HELP gateleen_storage_expand_requests_total  
# TYPE gateleen_storage_expand_requests_total counter
gateleen_storage_expand_requests_total 37.0

To enable the metrics, set a MeterRegistry instance by calling setMeterRegistry(MeterRegistry meterRegistry) method in ExpansionHandler class.