Basically, there are two types of extensions in STAC specification:
STAC documents extensions: these extensions can be defined in different elements of the document specification.
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:
In rstac package by including new functions make a
GitHub pull request on rstac repository
(https://github.com/brazil-data-cube/rstac)
In a new package by using rstac as dependent package
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:
begin of get_request() or post_request()
if STAC API version is not defined, try detect it
call endpoint()
call before_request()
send HTTP request
receive HTTP response
after_response()
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.
RSTACDocument(content, q, subclass)endpoint(q)
before_request(q)
after_response(q, res)
parse_params(q, params)
content_response(res, status_codes, content_types)
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)
The RSTACDocument() function returns a RSTACDocument object
with subclass defined by subclass parameter.
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.
a list data structure representing the JSON file
received in HTTP response (see content_response() function)
a RSTACQuery object.
a character corresponding to the subclass of the
object to be created.
a httr response object.
a named list with all URL query parameters to be
appended in the URL.
a character vector with successful
status codes.
a character vector with all acceptable
responses' content type.
a character vector with allowed HTTP request methods
a character with a personalized error message
either a RSTACQuery object expressing a STAC query
criteria or any RSTACDocument.
a character vector with all allowed S3 subclasses
a character vector with the names do omit.
a character with the STAC version.
a character informing the base URL of a
STAC web service.
RSTACDocument: The RSTACDocument() function is a constructor of
STAC documents. Currently, there are five STAC documents defined:
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.
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.
ext_query()