extensions: Extension development functions

extensionsR Documentation

Extension development functions

Description

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

  • STACCatalog

  • STACCollection

  • STACCollectionList

  • STACItem

  • STACItemCollection

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:

  • endpoint(): returns the endpoint value of the extension. Endpoints that vary between STAC API versions can be properly returned by checking the version field of RSTACQuery object.

  • before_request(): allows handling query parameters before submit them to the HTTP server;

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

These methods will work 'behind the scenes' when a RSTACQuery 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 endpoint()

  4. call before_request()

  5. send HTTP request

  6. receive HTTP response

  7. after_response()

  8. end of get_request() or post_request()

Besides that, the extension must expose a function to receive user parameters and return a RSTACQuery object with a subclass associated with the above S3 methods. This function must accept as its first parameter a RSTACQuery 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 RSTACQuery 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

endpoint(q)

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_subclass(x, subclasses)

subclass(x)

omit_query_params(q, names)

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

Arguments

q

a RSTACQuery 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

either a RSTACQuery object expressing a STAC query criteria or any RSTACDocument.

subclasses

a character vector with all allowed S3 subclasses

names

a character vector with the names do omit.

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 character endpoint value for endpoint() function. A RSTACQuery 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 RSTACQuery() 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_subclass(): The check_subclass() function specifies which type of query objects (RSTACQuery) or document objects (RSTACDocument) are expected in the function extension.

  • subclass(): The subclass() function returns a character representing the subclass name of either RSTACQuery or RSTACDocument S3 classes.

  • omit_query_params(): The omit_query_params() function was created to omit the paths that are defined as query parameters to simplify the creation of a query. Therefore, use this method only in endpoints that specify a parameter in their paths.

  • RSTACQuery(): The RSTACQuery() function is a constructor of RSTACQuery objects. Every extension must implement a subclass of RSTACQuery 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 Oct. 18, 2023, 1:15 a.m.