Class: QgsServerOgcApiHandler

An abstract class which represents an OGC API handler to be registered in QgsServerOgcApi class.

Subclasses must override operational and informative methods and define the core functionality in handleRequest() method.

The following methods MUST be implemented:

• path

• operationId

• summary (shorter text)

• description (longer text)

• linkTitle

• linkType

• schema

Optionally, override:

• tags

• parameters

• contentTypes

• defaultContentType

class Handler1(QgsServerOgcApiHandler):
  """Example handler"""

  def path(self):
      return QtCore.QRegularExpression("/handlerone")

  def operationId(self):
      return "handlerOne"

  def summary(self):
      return "First of its name"

  def description(self):
      return "The first handler ever"

  def linkTitle(self):
      return "Handler One Link Title"

  def linkType(self):
      return QgsServerOgcApi.data

  def handleRequest(self, context):
      """Simple mirror: returns the parameters"""

      params = self.values(context)
      self.write(params, context)

  def parameters(self, context):
      return [QgsServerQueryStringParameter("value1", True, QgsServerQueryStringParameter.Type.Double, "a double value")]

Added in version 3.10.

Note

This is an abstract class, with methods which must be implemented by a subclass.

The following methods must be implemented: description(), linkTitle(), linkType(), operationId(), path(), summary()

Class Hierarchy

Subclasses

QgsServerStaticHandler

Serves static files from the static path (resources/server/api/wfs3/static).

Abstract Methods

description	Description
linkTitle	Title for the handler link
linkType	Main role for the resource link
operationId	Returns the operation id for template file names and other internal references
path	URL pattern for this handler, named capture group are automatically extracted and returned by values()
summary	Summary

Methods

contentTypeForAccept	Looks for the first ContentType match in the accept header and returns its mime type, returns an empty string if there are not matches.
contentTypeFromRequest	Returns the content type from the request.
href	Returns an URL to self, to be used for links to the current resources and as a base for constructing links to sub-resources
setContentTypes	Set the content types to contentTypes
staticPath	Returns the absolute path to the base directory where static resources for this handler are stored in the given context.
templatePath	Returns the HTML template path for the handler in the given context
write	Writes data to the context response stream, content-type is calculated from the context request, optional htmlMetadata for the HTML templates can be specified and will be added as "metadata" to the HTML template variables.

Virtual Methods

In PyQGIS, only methods marked as virtual can be safely overridden in a Python subclass of QgsServerOgcApiHandler. See the FAQ for more details.

defaultContentType	Returns the default response content type in case the client did not specifically ask for any particular content type.
handleRequest	Handles the request within its context
parameters	Returns a list of query string parameters.
tags	Tags
values	Analyzes the incoming request context and returns the validated parameter map, throws QgsServerApiBadRequestError in case of errors.

Static Methods

layerFromCollectionId	Returns a vector layer from the collectionId in the given context.
parentLink	Returns a link to the parent page up to levels in the HTML hierarchy from the given url, MAP query argument is preserved

class qgis.server.QgsServerOgcApiHandler

Bases: object

contentTypeForAccept(self, accept: str | None) → str

Looks for the first ContentType match in the accept header and returns its mime type, returns an empty string if there are not matches.

Parameters:

accept (Optional[str])

Return type:

str

contentTypeFromRequest(self, request: QgsServerRequest | None) → QgsServerOgcApi.ContentType

Returns the content type from the request.

The path file extension is examined first and checked for known mime types, the “Accept” HTTP header is examined next. Fallback to the default content type of the handler if none of the above matches.

Raises:

QgsServerApiBadRequestError – if the content type of the request is not compatible with the handler (contentTypes() member)

Parameters:

request (Optional[QgsServerRequest])

Return type:

QgsServerOgcApi.ContentType

virtual defaultContentType(self) → QgsServerOgcApi.ContentType

Returns the default response content type in case the client did not specifically ask for any particular content type. The default implementation returns the first content type returned by contentTypes() or JSON if that list is empty.

Return type:

QgsServerOgcApi.ContentType

abstract description(self) → Any

virtual handleRequest(self, context: QgsServerApiContext)

Handles the request within its context

Subclasses must implement this methods, and call validate() to extract validated parameters from the request.

Raises:

QgsServerApiBadRequestError – if the method encounters any error

Parameters:

context (QgsServerApiContext)

href(self, context: QgsServerApiContext, extraPath: str | None = '', extension: str | None = '') → Any

Returns an URL to self, to be used for links to the current resources and as a base for constructing links to sub-resources

Parameters:

• context (QgsServerApiContext) – the current request context

• extraPath (Optional[str] = '') – an optional extra path that will be appended to the calculated URL

• extension (Optional[str] = '') – optional file extension to add (the dot will be added automatically).

Return type:

Any

static layerFromCollectionId(context: QgsServerApiContext, collectionId: str | None) → QgsVectorLayer | None

Returns a vector layer from the collectionId in the given context.

Raises:

QgsServerApiNotFoundError – if the layer could not be found.

Parameters:

• context (QgsServerApiContext)

• collectionId (Optional[str])

Return type:

Optional[QgsVectorLayer]

abstract linkTitle(self) → Any

Title for the handler link

Return type:

Any

abstract linkType(self) → QgsServerOgcApi.Rel

Main role for the resource link

Return type:

QgsServerOgcApi.Rel

abstract operationId(self) → Any

Returns the operation id for template file names and other internal references

Return type:

Any

virtual parameters(self, context: QgsServerApiContext) → List[QgsServerQueryStringParameter]

Returns a list of query string parameters.

Depending on the handler, it may be dynamic (per-request) or static.

Parameters:

context (QgsServerApiContext) – the request context

Return type:

List[QgsServerQueryStringParameter]

static parentLink(url: QUrl, levels: int = 1) → str

Returns a link to the parent page up to levels in the HTML hierarchy from the given url, MAP query argument is preserved

Parameters:

• url (QUrl)

• levels (int = 1)

Return type:

str

abstract path(self) → QRegularExpression

URL pattern for this handler, named capture group are automatically extracted and returned by values()

Example: “/handlername/(?P<code1>d{2})/items” will capture “code1” as a named parameter.

See also

values()

Return type:

QRegularExpression

setContentTypes(self, contentTypes: Iterable[int])

Set the content types to contentTypes

Parameters:

contentTypes (Iterable[int])

staticPath(self, context: QgsServerApiContext) → str

Returns the absolute path to the base directory where static resources for this handler are stored in the given context.

Parameters:

context (QgsServerApiContext)

Return type:

str

abstract summary(self) → Any

virtual tags(self) → List[str]

templatePath(self, context: QgsServerApiContext) → str

Returns the HTML template path for the handler in the given context

The template path is calculated from QgsServerSettings’s apiResourcesDirectory() as follow: apiResourcesDirectory() + “/ogc/templates/” + context.apiRootPath + operationId + “.html” e.g. for an API with root path “/wfs3” and an handler with operationId “collectionItems”, the path will be apiResourcesDirectory() + “/ogc/templates/wfs3/collectionItems.html”

Parameters:

context (QgsServerApiContext)

Return type:

str

virtual values(self, context: QgsServerApiContext) → Dict[str, Any]

Analyzes the incoming request context and returns the validated parameter map, throws QgsServerApiBadRequestError in case of errors.

Path fragments from the named groups in the path() regular expression are also added to the map.

Your handleRequest method should call this function to retrieve the parameters map.

Return type:

Dict[str, Any]

Returns:

the validated parameters map by extracting captured named parameters from the path (no validation is performed on the type because the regular expression can do it), and the query string parameters.

See also

path()

See also

parameters()

Raises:

QgsServerApiBadRequestError – if validation fails

Parameters:

context (QgsServerApiContext)

write(self, data: Any, context: QgsServerApiContext, htmlMetadata: Dict[str, Any] = {})

Writes data to the context response stream, content-type is calculated from the context request, optional htmlMetadata for the HTML templates can be specified and will be added as “metadata” to the HTML template variables.

HTML output uses a template engine.

Available template functions: See: https://github.com/pantor/inja#tutorial

Available custom template functions:

• path_append( path ): appends a directory path to the current url

• path_chomp( n ): removes the specified number “n” of directory components from the current url path

• json_dump( ): prints current JSON data passed to the template

• static( path ): returns the full URL to the specified static path, for example: static( “/style/black.css” ) will return something like “/wfs3/static/style/black.css”

• links_filter( links, key, value ): returns filtered links from a link list

• content_type_name( content_type ): returns a short name from a content type for example “text/html” will return “HTML”

• nl2br( text ): returns the input text with all newlines replaced by “<br>” tags

• starts_with( string, prefix ): returns true if a string begins with the provided string prefix, false otherwise

Parameters:

• data (Any)

• context (QgsServerApiContext)

• htmlMetadata (Dict[str, Any] = {})