Importante

unireLa traduzione è uno sforzo comunitario you can join. Questa pagina è attualmente tradotta al 100.00%.

20. QGIS Server e Python

20.1. Introduzione

Per saperne di più su QGIS Server, leggi il QGIS Server Guida/Manuale.

QGIS Server è tre cose diverse:

1. Libreria QGIS Server: una libreria che fornisce un’API per la creazione di servizi web OGC.

2. QGIS Server FCGI: un’applicazione binaria FCGI qgis_mapserv.fcgi che, insieme a un server web, implementa una serie di servizi OGC (WMS, WFS, WCS ecc.) e API OGC (WFS3/OAPIF).

3. QGIS Development Server: un’applicazione binaria del server di sviluppo qgis_mapserver che implementa una serie di servizi OGC (WMS, WFS, WCS ecc.) e di API OGC (WFS3/OAPIF).

Questo capitolo del manuale si concentra sul primo argomento e, spiegando l’uso dell’API del server QGIS, mostra come sia possibile usare Python per estendere, migliorare o personalizzare il comportamento del server o come usare l’API del server QGIS per incorporare il server QGIS in un’altra applicazione.

Esistono diversi modi con cui puoi alterare il comportamento di QGIS Server o per estendere le sue capabilities per offrire nuovi servizi personalizzati o API:

• EMBEDDING → Usare l’API del server QGIS da un’altra applicazione Python

• STANDALONE → Eseguire QGIS Server come servizio WSGI/HTTP standalone

• FILTRI → Migliorare/Personalizzare QGIS Server con i plugin di filtro

• SERVICES → Aggiungere un nuovo SERVICE

• API OGC → Aggiungere una nuova OGC API

Le applicazioni embedding e standalone richiedono l’utilizzo dell’API Python di QGIS Server direttamente da un altro script o applicazione Python. Le altre opzioni sono più adatte quando vuoi aggiungere funzionalità personalizzate a un’applicazione binaria standard di QGIS Server (FCGI o server di sviluppo): in questo caso dovrai scrivere un plugin Python per l’applicazione server e registrare i tuoi filtri, servizi o API personalizzati.

20.2. Nozioni di base server API

Le classi fondamentali coinvolte in una tipica applicazione di QGIS Server sono:

• QgsServer l’istanza del server (in genere una singola istanza per tutta la durata dell’applicazione)

• QgsServerRequest l’oggetto richiesta (tipicamente ricreato ad ogni richiesta)

• QgsServer.handleRequest(request, response) elabora la richiesta e popola la risposta.

Il flusso di lavoro di QGIS Server FCGI o server di sviluppo può essere riassunto come segue:

initialize the QgsApplication
create the QgsServer
the main server loop waits forever for client requests:
    for each incoming request:
        create a QgsServerRequest request
        create a QgsServerResponse response
        call QgsServer.handleRequest(request, response)
            filter plugins may be executed
        send the output to the client

All’interno del metodo QgsServer.handleRequest(request, response) vengono richiamate le callback dei plugin di filtro e QgsServerRequest e QgsServerResponse sono resi disponibili ai plugin attraverso la classe QgsServerInterface.

Avvertimento

Le classi del server QGIS non sono thread safe; per la creazione di applicazioni scalabili basate sull’API del server QGIS, devi utilizzare sempre un modello multiprocesso o dei container.

20.3. Standalone o embedding

Per le applicazioni server standalone o incorporate, è necessario utilizzare direttamente le classi server di cui sopra, impacchettandole in un’implementazione del server web che gestisce tutte le interazioni del protocollo HTTP con il client.

Segue un esempio minimo di utilizzo dell’API di QGIS Server (senza la parte HTTP):

from qgis.core import QgsApplication
from qgis.server import *
app = QgsApplication([], False)

# Create the server instance, it may be a single one that
# is reused on multiple requests
server = QgsServer()

# Create the request by specifying the full URL and an optional body
# (for example for POST requests)
request = QgsBufferServerRequest(
    'http://localhost:8081/?MAP=/qgis-server/projects/helloworld.qgs' +
    '&SERVICE=WMS&REQUEST=GetCapabilities')

# Create a response objects
response = QgsBufferServerResponse()

# Handle the request
server.handleRequest(request, response)

print(response.headers())
print(response.body().data().decode('utf8'))

app.exitQgis()

Ecco un esempio completo di applicazione standalone sviluppata per il test delle integrazioni continue sul repository del codice sorgente di QGIS, che mette in mostra un’ampia serie di diversi filtri per i plugin e schemi di autenticazione (non sono adatti alla produzione perché sono stati sviluppati solo a scopo di test, ma sono comunque interessanti per l’apprendimento): qgis_wrapped_server.py.

20.4. Plugin del server

I plugin python del server vengono caricati al momento dell’avvio dell’applicazione QGIS Server e possono essere utilizzati per registrare filtri, servizi o API.

La struttura di un plugin server è molto simile alla sua omologa desktop, un oggetto QgsServerInterface è reso disponibile ai plugin e questi ultimi possono registrare uno o più filtri, servizi o API personalizzati nel registro corrispondente, utilizzando uno dei metodi esposti dall’interfaccia server.

20.4.1. Plugin filtro server

I filtri sono disponibili in tre varianti e possono essere istanziati sottoclassando una delle classi seguenti e richiamando il metodo corrispondente di QgsServerInterface:

Tipo filtro	Classe base	Registrazione QgsServerInterface
I/O	QgsServerFilter	registerFilter()
Controllo accessi	QgsAccessControlFilter	registerAccessControl()
Cache	QgsServerCacheFilter	registerServerCache()

20.4.1.1. Filtri I/O

I filtri I/O possono modificare l’input e l’output del server (la richiesta e la risposta) dei servizi principali (WMS, WFS ecc.), consentendo di effettuare qualsiasi tipo di manipolazione del flusso di lavoro dei servizi. È possibile, ad esempio, limitare l’accesso a layer selezionati, inserire un foglio di stile XSL nella risposta XML, aggiungere un watermark a un’immagine WMS generata e così via.

A questo punto, ti può essere utile una rapida occhiata ai server plugins API docs.

Ogni filtro deve implementare almeno uno dei tre callback:

• onRequestReady()

• onResponseComplete()

• onSendResponse()

Tutti i filtri hanno accesso all’oggetto request/response (QgsRequestHandler) e possono manipolare tutte le sue proprietà (input/output) e sollevare eccezioni (anche se in modo piuttosto particolare, come vedremo più avanti).

Tutti questi metodi restituiscono un valore booleano che indica se la call deve essere propagata ai filtri successivi. Se uno di questi metodi restituisce False, la catena si ferma, altrimenti la call si propagherà al filtro successivo.

Ecco lo pseudo-codice che mostra come il server gestisce una richiesta tipica e quando vengono richiamati i callback del filtro:

for each incoming request:
    create GET/POST request handler
    pass request to an instance of QgsServerInterface
    call onRequestReady filters

    if there is not a response:
        if SERVICE is WMS/WFS/WCS:
            create WMS/WFS/WCS service
            call service’s executeRequest
                possibly call onSendResponse for each chunk of bytes
                sent to the client by a streaming services (WFS)
        call onResponseComplete
    request handler sends the response to the client

I paragrafi seguenti descrivono in dettaglio i callback disponibili.

20.4.1.1.1. onRequestReady

Viene chiamato quando la richiesta è pronta: l’URL e i dati in entrata sono stati analizzati e prima di entrare nei servizi principali (WMS, WFS ecc.) si passa a questo punto in cui puoi manipolare l’input ed eseguire azioni come:

• autenticazione/autorizzazione

• redirects

• aggiungere/rimuovere alcuni parametri (ad esempio i nomi dei tipi)

• sollevare eccezioni

Potresti anche sostituire completamente un servizio principale cambiando il parametro SERVICE e quindi bypassando completamente il servizio principale (non che questo abbia molto senso, però).

20.4.1.1.2. onSendResponse

Viene richiamato ogni volta che un output parziale viene scaricato dal buffer di risposta (cioè a FCGI stdout se si usa il server fcgi) e da lì al client. Questo accade quando vengono trasmessi contenuti enormi (come WFS GetFeature). In questo caso onSendResponse() può essere chiamato più volte.

Da notare che se la risposta non è in streaming, onSendResponse() non sarà chiamato affatto.

In ogni caso, l’ultimo (o unico) blocco sarà inviato al client dopo una chiamata a onResponseComplete().

Il ritorno di False impedisce il trasferimento dei dati al client. Questo è auspicabile quando un plugin vuole raccogliere tutti i blocchi di una risposta ed esaminare o modificare la risposta in onResponseComplete().

20.4.1.1.3. onResponseComplete

Questo metodo viene richiamato una volta quando i servizi di base (se sono attivi) terminano il loro processo e la richiesta è pronta per essere inviata al client. Come discusso in precedenza, questo metodo sarà chiamato prima che l’ultimo (o unico) blocco di dati sia inviato al client. Per i servizi di streaming, potrebbero essere state chiamate più volte onSendResponse().

onResponseComplete() è il luogo ideale per fornire l’implementazione di nuovi servizi (WPS o servizi personalizzati) e per eseguire la manipolazione diretta dell’output proveniente dai servizi principali (ad esempio per aggiungere una filigrana a un’immagine WMS).

Da notare che la restituzione di False impedirà ai plugin successivi di eseguire onResponseComplete() ma, in ogni caso, impedirà l’invio della risposta al client.

20.4.1.1.4. Generazione di eccezioni da parte di un plugin

C’è ancora del lavoro da fare su questo argomento: l’implementazione attuale può distinguere tra eccezioni gestite e non gestite impostando una proprietà QgsRequestHandler a un’istanza di QgsMapServiceException, in questo modo il codice principale C++ può catturare le eccezioni python gestite e ignorare quelle non gestite (o meglio: registrarle).

Questo approccio fondamentalmente funziona, ma non è molto «pythonic»: un approccio migliore sarebbe quello di sollevare eccezioni dal codice python e vederle confluire nel ciclo C++ per essere gestite lì.

20.4.1.1.5. Scrivere un server plugin

Un plugin server è un plugin Python standard di QGIS, come descritto in Sviluppo di plugin Python, che fornisce solo un’interfaccia aggiuntiva (o alternativa): un tipico plugin desktop di QGIS ha accesso all’applicazione QGIS attraverso l’istanza QgisInterface, un plugin server ha accesso solo a una QgsServerInterface quando viene eseguito nel contesto dell’applicazione QGIS Server.

Per far sì che QGIS Server sappia che un plugin ha un’interfaccia server, è necessaria una voce di metadati speciale (in metadata.txt):

server=True

Importante

Solo i plugin con i metadati server=True saranno caricati ed eseguiti da QGIS Server.

Il plugin di esempio qgis3-server-vagrant discusso qui (con molti altri) è disponibile su github, alcuni plugin per server sono anche pubblicati nel repository ufficiale dei QGIS plugins.

20.4.1.1.5.1. Plugin file

Ecco la struttura delle cartelle del nostro plugin server di esempio.

PYTHON_PLUGINS_PATH/
  HelloServer/
    __init__.py    --> *required*
    HelloServer.py  --> *required*
    metadata.txt   --> *required*

20.4.1.1.5.1.1. __init__.py

Questo file è richiesto dal sistema di importazione di Python. Inoltre, QGIS Server richiede che questo file contenga una funzione serverClassFactory(), che viene chiamata quando il plugin viene caricato in QGIS Server all’avvio del server. Riceve un riferimento all’istanza di QgsServerInterface e deve restituire l’istanza della classe del plugin. Ecco come appare il plugin di esempio __init__.py:

def serverClassFactory(serverIface):
    from .HelloServer import HelloServerServer
    return HelloServerServer(serverIface)

20.4.1.1.5.1.2. HelloServer.py

È qui che avviene la magia e questo è l’aspetto della magia: (ad esempio HelloServer.py)

Un plugin server consiste tipicamente in uno o più callback racchiusi in istanze di una QgsServerFilter.

Ogni QgsServerFilter implementa uno o più dei seguenti callback:

• onRequestReady()

• onResponseComplete()

• onSendResponse()

L’esempio seguente implementa un filtro minimo che stampa HelloServer! nel caso in cui il parametro SERVICE sia uguale a «HELLO»:

class HelloFilter(QgsServerFilter):

    def __init__(self, serverIface):
        super().__init__(serverIface)

    def onRequestReady(self) -> bool:
        QgsMessageLog.logMessage("HelloFilter.onRequestReady")
        return True

    def onSendResponse(self) -> bool:
        QgsMessageLog.logMessage("HelloFilter.onSendResponse")
        return True

    def onResponseComplete(self) -> bool:
        QgsMessageLog.logMessage("HelloFilter.onResponseComplete")
        request = self.serverInterface().requestHandler()
        params = request.parameterMap()
        if params.get('SERVICE', '').upper() == 'HELLO':
            request.clear()
            request.setResponseHeader('Content-type', 'text/plain')
            # Note that the content is of type "bytes"
            request.appendBody(b'HelloServer!')
        return True

I filtri devono essere registrati nella serverIface come nell’esempio seguente:

class HelloServerServer:
    def __init__(self, serverIface):
        serverIface.registerFilter(HelloFilter(serverIface), 100)

Il secondo parametro di registerFilter() imposta una priorità che definisce l’ordine delle callback con lo stesso nome (la priorità più bassa viene invocata per prima).

Utilizzando i tre callback, i plugin possono manipolare l’input e/o l’output del server in molti modi diversi. In ogni momento, l’istanza del plugin ha accesso alla QgsRequestHandler attraverso la QgsServerInterface. La classe QgsRequestHandler ha molti metodi che possono essere usati per modificare i parametri di ingresso prima di entrare nel nucleo di elaborazione del server (usando requestReady()) o dopo che la richiesta è stata elaborata dai servizi centrali (usando sendResponse()).

I seguenti esempi coprono alcuni casi d’uso comuni:

20.4.1.1.5.2. Modificare l’input

Il plugin di esempio contiene un esempio di test che modifica i parametri di input provenienti dalla stringa di query; in questo esempio un nuovo parametro viene inserito nella parameterMap (già analizzata), questo parametro è poi visibile dai servizi di base (WMS, ecc.); alla fine dell’elaborazione dei servizi di base controlliamo che il parametro sia ancora presente:

class ParamsFilter(QgsServerFilter):

    def __init__(self, serverIface):
        super(ParamsFilter, self).__init__(serverIface)

    def onRequestReady(self) -> bool:
        request = self.serverInterface().requestHandler()
        params = request.parameterMap( )
        request.setParameter('TEST_NEW_PARAM', 'ParamsFilter')
        return True

    def onResponseComplete(self) -> bool:
        request = self.serverInterface().requestHandler()
        params = request.parameterMap( )
        if params.get('TEST_NEW_PARAM') == 'ParamsFilter':
            QgsMessageLog.logMessage("SUCCESS - ParamsFilter.onResponseComplete")
        else:
            QgsMessageLog.logMessage("FAIL    - ParamsFilter.onResponseComplete")
        return True

Questo è un estratto di ciò che vedi nel file di log:

src/core/qgsmessagelog.cpp: 45: (logMessage) [0ms] 2014-12-12T12:39:29 plugin[0] HelloServerServer - loading filter ParamsFilter
src/core/qgsmessagelog.cpp: 45: (logMessage) [1ms] 2014-12-12T12:39:29 Server[0] Server plugin HelloServer loaded!
src/core/qgsmessagelog.cpp: 45: (logMessage) [0ms] 2014-12-12T12:39:29 Server[0] Server python plugins loaded
src/mapserver/qgshttprequesthandler.cpp: 547: (requestStringToParameterMap) [1ms] inserting pair SERVICE // HELLO into the parameter map
src/mapserver/qgsserverfilter.cpp: 42: (onRequestReady) [0ms] QgsServerFilter plugin default onRequestReady called
src/core/qgsmessagelog.cpp: 45: (logMessage) [0ms] 2014-12-12T12:39:29 plugin[0] SUCCESS - ParamsFilter.onResponseComplete

Nella riga evidenziata, la stringa «SUCCESS» indica che il plugin ha superato il test.

La stessa tecnica può essere sfruttata per utilizzare un servizio personalizzato al posto di quello principale: puoi ad esempio ignorare una richiesta WFS SERVICE o qualsiasi altra richiesta principale semplicemente cambiando il parametro SERVICE in qualcosa di diverso e il servizio principale verrà ignorato. Puoi quindi inserire i tuoi risultati personalizzati nell’output e inviarli al client (questo è spiegato più avanti).

Suggerimento

Se vuoi davvero implementare un servizio personalizzato, si raccomanda di sottoclassare QgsService e di registrare il tuo servizio su registerFilter() chiamando il suo registerService(service).

20.4.1.1.5.3. Modifica o sostituzione del risultato

L’esempio del filtro watermark mostra come sostituire l’output WMS con una nuova immagine ottenuta aggiungendo un’immagine watermark all’immagine WMS generata dal servizio centrale WMS:

from qgis.server import *
from qgis.PyQt.QtCore import *
from qgis.PyQt.QtGui import *

class WatermarkFilter(QgsServerFilter):

    def __init__(self, serverIface):
        super().__init__(serverIface)

    def onResponseComplete(self) -> bool:
        request = self.serverInterface().requestHandler()
        params = request.parameterMap( )
        # Do some checks
        if (params.get('SERVICE').upper() == 'WMS' \
                and params.get('REQUEST').upper() == 'GETMAP' \
                and not request.exceptionRaised() ):
            QgsMessageLog.logMessage("WatermarkFilter.onResponseComplete: image ready %s" % request.parameter("FORMAT"))
            # Get the image
            img = QImage()
            img.loadFromData(request.body())
            # Adds the watermark
            watermark = QImage(os.path.join(os.path.dirname(__file__), 'media/watermark.png'))
            p = QPainter(img)
            p.drawImage(QRect( 20, 20, 40, 40), watermark)
            p.end()
            ba = QByteArray()
            buffer = QBuffer(ba)
            buffer.open(QIODevice.WriteOnly)
            img.save(buffer, "PNG" if "png" in request.parameter("FORMAT") else "JPG")
            # Set the body
            request.clearBody()
            request.appendBody(ba)
        return True

In questo esempio viene controllato il valore del parametro SERVICE e se la richiesta in arrivo è un WMS GETMAP e non sono state impostate eccezioni da un plugin precedentemente eseguito o dal servizio principale (WMS in questo caso), l’immagine generata da WMS viene recuperata dal buffer di output e viene aggiunta l’immagine del watermark. Il passo finale consiste nel cancellare il buffer di output e sostituirlo con la nuova immagine generata. Si noti che in una situazione reale si dovrebbe verificare anche il tipo di immagine richiesta, invece di supportare solo PNG o JPG.

20.4.1.2. Filtri controllo accesso

I filtri di controllo degli accessi danno allo sviluppatore un controllo a grana fine sui layer, sugli elementi e sugli attributi a cui si può accedere; le seguenti callback possono essere implementate in un filtro di controllo degli accessi:

• layerFilterExpression(layer)

• layerFilterSubsetString(layer)

• layerPermissions(layer)

• authorizedLayerAttributes(layer, attributes)

• allowToEdit(layer, feature)

• cacheKey()

20.4.1.2.1. Plugin file

Ecco la struttura dello cartella del nostro plugin di esempio:

PYTHON_PLUGINS_PATH/
  MyAccessControl/
    __init__.py    --> *required*
    AccessControl.py  --> *required*
    metadata.txt   --> *required*

20.4.1.2.1.1. __init__.py

Questo file è richiesto dal sistema di importazione di Python. Come per tutti i plugin del server QGIS, questo file contiene una funzione serverClassFactory(), che viene chiamata quando il plugin viene caricato in QGIS Server all’avvio. Riceve un riferimento a un’istanza di QgsServerInterface e deve restituire un’istanza della classe del plugin. Ecco come appare il plugin di esempio __init__.py:

def serverClassFactory(serverIface):
    from MyAccessControl.AccessControl import AccessControlServer
    return AccessControlServer(serverIface)

20.4.1.2.1.2. AccessControl.py

class AccessControlFilter(QgsAccessControlFilter):

    def __init__(self, server_iface):
        super().__init__(server_iface)

    def layerFilterExpression(self, layer):
        """ Return an additional expression filter """
        return super().layerFilterExpression(layer)

    def layerFilterSubsetString(self, layer):
        """ Return an additional subset string (typically SQL) filter """
        return super().layerFilterSubsetString(layer)

    def layerPermissions(self, layer):
        """ Return the layer rights """
        return super().layerPermissions(layer)

    def authorizedLayerAttributes(self, layer, attributes):
        """ Return the authorised layer attributes """
        return super().authorizedLayerAttributes(layer, attributes)

    def allowToEdit(self, layer, feature):
        """ Are we authorised to modify the following geometry """
        return super().allowToEdit(layer, feature)

    def cacheKey(self):
        return super().cacheKey()

class AccessControlServer:

   def __init__(self, serverIface):
      """ Register AccessControlFilter """
      serverIface.registerAccessControl(AccessControlFilter(serverIface), 100)

Questo esempio offre un accesso completo a tutti.

Il ruolo del plugin è quello di sapere chi è connesso.

In tutti questi metodi abbiamo il parametro layer on per poter personalizzare la restrizione per layer.

20.4.1.2.2. layerFilterExpression

Si usa per aggiungere una Espressione per limitare i risultati.

Ad esempio, per limitare gli elementi in cui l’attributo ``role”” è uguale a ``user””.

def layerFilterExpression(self, layer):
    return "$role = 'user'"

20.4.1.2.3. layerFilterSubsetString

Come il precedente, ma utilizzando la SubsetString (eseguita nel database).

Ad esempio, per limitare gli elementi in cui l’attributo ``role”” è uguale a ``user””.

def layerFilterSubsetString(self, layer):
    return "role = 'user'"

20.4.1.2.4. layerPermissions

Limitare l’accesso al layer.

Restituisce un oggetto di tipo LayerPermissions(), che ha le proprietà:

• canRead per vederlo in GetCapabilities e avere accesso in lettura.

• canInsert per poter inserire un nuovo elemento.

• canUpdate per poter aggiornare un elemento.

• canDelete per poter eliminare un elemento.

Ad esempio, per limitare l’accesso in sola lettura:

def layerPermissions(self, layer):
    rights = QgsAccessControlFilter.LayerPermissions()
    rights.canRead = True
    rights.canInsert = rights.canUpdate = rights.canDelete = False
    return rights

20.4.1.2.5. authorizedLayerAttributes

Si usa per limitare la visibilità di un sottoinsieme specifico di attributi.

Il parametro attributo restituisce l’insieme corrente degli attributi visibili.

Ad esempio, per nascondere l’attributo ``role””:

def authorizedLayerAttributes(self, layer, attributes):
    return [a for a in attributes if a != "role"]

20.4.1.2.6. allowToEdit

Viene utilizzato per limitare la modifica di un sottoinsieme di elementi.

È utilizzato nel protocollo WFS-Transaction.

Ad esempio, per poter modificare solo gli elementi che hanno l’attributo role` con il valore user:

def allowToEdit(self, layer, feature):
    return feature.attribute('role') == 'user'

20.4.1.2.7. cacheKey

QGIS Server mantiene una cache delle caratteristiche, quindi per avere una cache per role si può indicare role in questo metodo. Oppure restituire None per disabilitare completamente la cache.

20.4.2. Servizi personalizzati

In QGIS Server, i servizi principali come WMS, WFS e WCS sono implementati come sottoclassi di QgsService.

Per implementare un nuovo servizio che verrà eseguito quando il parametro della query string SERVICE corrisponde al nome del servizio, puoi implementare la tua QgsService e registrare il tuo servizio nel serviceRegistry() chiamando il suo registerService(service).

Ecco un esempio di servizio personalizzato chiamato CUSTOM:

from qgis.server import QgsService
from qgis.core import QgsMessageLog

class CustomServiceService(QgsService):

    def __init__(self):
        QgsService.__init__(self)

    def name(self):
        return "CUSTOM"

    def version(self):
        return "1.0.0"

    def executeRequest(self, request, response, project):
        response.setStatusCode(200)
        QgsMessageLog.logMessage('Custom service executeRequest')
        response.write("Custom service executeRequest")


class CustomService():

    def __init__(self, serverIface):
        serverIface.serviceRegistry().registerService(CustomServiceService())

20.4.3. API personalizzate

In QGIS Server, le API OGC di base come OAPIF (alias WFS3) sono implementate come collezioni di QgsServerOgcApiHandler che sono registrate in un’istanza di QgsServerOgcApi (o della sua classe madre QgsServerApi).

Per implementare una nuova API che verrà eseguita quando il percorso dell’url corrisponde a un determinato URL, puoi implementare le tue istanze QgsServerOgcApiHandler, aggiungerle a una QgsServerOgcApi e registrare l’API nel serviceRegistry() chiamando il suo registerApi(api).

Ecco un esempio di API personalizzata che verrà eseguita quando l’URL contiene /customapi:

import json
import os

from qgis.PyQt.QtCore import QBuffer, QIODevice, QTextStream, QRegularExpression
from qgis.server import (
    QgsServiceRegistry,
    QgsService,
    QgsServerFilter,
    QgsServerOgcApi,
    QgsServerQueryStringParameter,
    QgsServerOgcApiHandler,
)

from qgis.core import (
    QgsMessageLog,
    QgsJsonExporter,
    QgsCircle,
    QgsFeature,
    QgsPoint,
    QgsGeometry,
)


class CustomApiHandler(QgsServerOgcApiHandler):

    def __init__(self):
        super(CustomApiHandler, self).__init__()
        self.setContentTypes([QgsServerOgcApi.HTML, QgsServerOgcApi.JSON])

    def path(self):
        return QRegularExpression("/customapi")

    def operationId(self):
        return "CustomApiXYCircle"

    def summary(self):
        return "Creates a circle around a point"

    def description(self):
        return "Creates a circle around a point"

    def linkTitle(self):
        return "Custom Api XY Circle"

    def linkType(self):
        return QgsServerOgcApi.data

    def handleRequest(self, context):
        """Simple Circle"""

        values = self.values(context)
        x = values['x']
        y = values['y']
        r = values['r']
        f = QgsFeature()
        f.setAttributes([x, y, r])
        f.setGeometry(QgsCircle(QgsPoint(x, y), r).toCircularString())
        exporter = QgsJsonExporter()
        self.write(json.loads(exporter.exportFeature(f)), context)

    def templatePath(self, context):
        # The template path is used to serve HTML content
        return os.path.join(os.path.dirname(__file__), 'circle.html')

    def parameters(self, context):
        return [QgsServerQueryStringParameter('x', True, QgsServerQueryStringParameter.Type.Double, 'X coordinate'),
                QgsServerQueryStringParameter(
                    'y', True, QgsServerQueryStringParameter.Type.Double, 'Y coordinate'),
                QgsServerQueryStringParameter('r', True, QgsServerQueryStringParameter.Type.Double, 'radius')]


class CustomApi():

    def __init__(self, serverIface):
        api = QgsServerOgcApi(serverIface, '/customapi',
                            'custom api', 'a custom api', '1.1')
        handler = CustomApiHandler()
        api.registerHandler(handler)
        serverIface.serviceRegistry().registerApi(api)