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:
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 onrstac
repository (https://github.com/brazil-data-cube/rstac)In a new package by using
rstac
as dependent packageIn 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 theversion
field ofRSTACQuery
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()
orpost_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()
orpost_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 = c("message", "description", "detail")
)
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 anyRSTACDocument
.- 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()
: Thecontent_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()
: Thecheck_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()
: Thecheck_subclass()
function specifies which type of query objects (RSTACQuery
) or document objects (RSTACDocument
) are expected in the function extension.subclass()
: Thesubclass()
function returns acharacter
representing the subclass name of eitherRSTACQuery
orRSTACDocument
S3 classes.omit_query_params()
: Theomit_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()
: TheRSTACQuery()
function is a constructor ofRSTACQuery
objects. Every extension must implement a subclass ofRSTACQuery
to represent its queries. This is done by informing to thesubclass
parameter the extension's subclass name.The
params
parameter is a namedlist
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 useutils::modifyList()
function to merge the old and new query parameters.If the
version
parameter isNULL
,rstac
will detect STAC API version automatically.In general, if you are implementing a new subclass, the parameters
version
andurl
will be the same as the previous query. Theparams
parameter will be merged with previous query. And subclass is the extension's subclass name.