extensions: Extension development functions

In rstac: Client Library for SpatioTemporal Asset Catalog

Extension development functions

Description

Currently, there are five STAC documents defined in STAC spec:

• doc_catalog

• doc_collection

• doc_collections

• doc_item

• doc_items

Each document class is associated with STAC API endpoints. As soon as new STAC documents are proposed in the specification, new classes can be created in the rstac package.

Let version parameter NULL to detect version automatically.

Basically, there are two types of extensions in STAC specification:

1. STAC documents extensions: these extensions can be defined in different elements of the document specification.

2. STAC API extensions: these extensions are associated with the interaction between the client and server through API and may add new elements in the STAC documents or just filter the elements to be returned in the documents.

Here, we will focus on the second type of extension.

To let rstac package perform some behavior according to an STAC API extension we need define some functions. These functions can be implemented in three environments:

1. In rstac package by including new functions make a GitHub pull request on rstac repository (https://github.com/brazil-data-cube/rstac)

2. In a new package by using rstac as dependent package

3. In a script that loads rstac into the environment

All these places may impose specific requirements, however the core logic to implement an extension is the same.

These functions are intended for those who want to implement new STAC API extensions. An extension must define a subclass name and implement all the following S3 generic methods for that subclass:

• before_request(): allows handling query parameters before submit them to the HTTP server, usually sets up the query endpoint;

• after_request(): allows to check and parse document received by the HTTP server;

These methods will work 'behind the scenes' when a rstac_query object representing a user query are passed to a request function (e.g. get_request() or post_request()). The calling order is:

1. begin of get_request() or post_request()

2. if STAC API version is not defined, try detect it

3. call before_request()

4. send HTTP request

5. receive HTTP response

6. after_response()

7. end of get_request() or post_request()

Besides that, the extension must expose a function to receive user parameters and return a rstac_query object with a subclass associated with the above S3 methods. This function must accept as its first parameter a rstac_query object representing the actual query. To keep the command flow consistency, the function needs to check the subclass of the input query. After that, it must set new or changes the input query parameters according to the user input and, finally, return the new query as a rstac_query object.

You can see examples on how to implement an STAC API extension by looking at stac.R, collections.R, items.R, stac_search.R, and ext_query.R source files. These files implement core STAC API endpoints, as well as the query API extension.

There are also some utility functions described in Functions section bellow that can help the extension development.

Usage

before_request(q)

after_response(q, res)

parse_params(q, params)

content_response(res, status_codes, content_types, key_message)

check_query_verb(q, verbs, msg = NULL)

check_query(x, classes = NULL)

subclass(x)

set_query_endpoint(q, endpoint, params = NULL)

rstac_query(version = NULL, base_url, params = list(), subclass)

Arguments

q	a rstac_query object.
res	a httr response object.
params	a named list with all URL query parameters to be appended in the URL.
status_codes	a character vector with successful status codes.
content_types	a character vector with all acceptable responses' content type.
key_message	a character vector with the JSON keys to show the requested API message.
verbs	a character vector with allowed HTTP request methods
msg	a character with a personalized error message
x	a rstac_query object expressing a STAC query criteria.
classes	a character vector with all allowed S3 sub-classes
endpoint	a character vector with the format string with the endpoint url.
version	a character with the STAC version.
base_url	a character informing the base URL of a STAC web service.
subclass	a character corresponding to the subclass of the object to be created.

Value

A rstac_query object for before_request() and after_response() functions.

The content_response() function returns a list data structure representing the JSON file received in HTTP response

The rstac_query() function returns a STACQuery object with subclass defined by subclass parameter.

Functions

• content_response(): The content_response function checks if the request's response is in accordance with the allowed status codes and content-types. It returns the parsed content response.

• check_query_verb(): The check_query_verb() function allows you to define which HTTP verbs are allowed. It is useful for establishing which verbs will be supported by an extension.

• check_query(): The check_query() function specifies which type of query object (rstac_query) is expected in the function extension.

• subclass(): The subclass() function returns a character representing the subclass name of rstac_query objects.

• set_query_endpoint(): The set_query_endpoint() function defines the endpoint of a query. If params parameter is passed, each value must be an entry of params field of the given query. The corresponding param value will be used as value replacement of ⁠%s⁠ occurrences in the endpoint string. After the replacement, all params in this list will be removed.

• rstac_query(): The rstac_query() function is a constructor of rstac_query objects. Every extension must implement a subclass of rstac_query to represent its queries. This is done by informing to the subclass parameter the extension's subclass name.

  The params parameter is a named list where user parameters must be stored. It is important to know if previous query parameters needs to be keeped in the new query. If so, it is recommended do use utils::modifyList() function to merge the old and new query parameters.

  If the version parameter is NULL, rstac will detect STAC API version automatically.

  In general, if you are implementing a new subclass, the parameters version and url will be the same as the previous query. The params parameter will be merged with previous query. And subclass is the extension's subclass name.

See Also

ext_query()

rstac documentation built on Sept. 11, 2024, 7:03 p.m.