Connexion

Ernesto Rico Schmidt am 16. August 2019

Wenn aus Angeben eine richtige REST-Schnitstelle werden kann.

Connexion ist ein Framework, das aus einer REST-Schnittstellenbescheibung mit OpenAPI, mit Hilfe von Flask, HTTP Endpoints verarbeiten kann.

Die OpenAPI Specification ist der Nachfolgerin von Swagger, die ursprünglich 2011 von SmartBear entwickelt, 2015 der Linux Foundation übergeben wurde und ein Jahr später in OpenAPI ungetauft wurde.

Über die Spezifikation wacht ein sogenanntes Open Collaborative Project der Linux Foundation, zu der nicht nur SmartBear selbst gehört, sondern auch 3Scale, Apigee, Capital One, Google, IBM, Intuit, Microsoft, PayPal, Restlet.

Die Version 3.0 der Spezifikation wurde 2107 freigegeben und erlaubt nicht nur die Beschreibung der REST-Schnittstelle stammt Beispielantworten. Mit Connexion können die Enpoints zu Python Funktionen (die mit Flask implementiert sind) zugeordnet werden.

Andere Werkzeuge erzeugen die Spezifikation auf Basis der (Python-)Implementierung, bzw. generieren den Rumpf der Implementierung auf Basis der Spezifikation.

Installation

Für unseres Beispiel verwenden wir Connexion in einer virtuellen Umgebungen, in der wir alle nötigen Abhängigkeiten installieren:

$ python3 -m vena venv
$ source venv/bin/activate
(venv) $ pip install connexion[swagger-ui]

YAML

YAML ist eine für Menschen lesbare Sprache zur Serialisierung von Daten. Sie wird oft in Konfigurationsdateien eingesetzt und verwendet Einrückungen wie Python um Verschachtelung anzuzeigen.

Eine REST-Schnitstelle wird in der OpenAPI-Spezifikation mit YAML beschrieben.

REST-Schnittstelle für pislea

Eine sehr einfache REST-Schnittstelle für PISLEA hat nur zwei Endpoints, und unterstützt nur die GET-Methode.

  • Der nächste Stichtag im „Plan zur Implementierung von Freier Software und Offene Standards“,
  • Die vergangenen Stichtage im „Plan zur Implementierung von Freier Software und Offene Standards“.

Beide Teile verwenden die Beschreibung des Elements Fecha bzw. des Arrays Fechas.

# pislea-v1.yaml
openapi: "3.0.0"
  info:
  version: 1.0.0
  title: 
  license:
    name: BSD
  servers:
  - url: https://api.pislea.bolivia.bo/v1   
paths:
  /próxima-fecha:
    get:
      summary: Der nächste Stichtag
      operationId: próxima_fecha
      responses:
        '200':
          description: Die Daten des nächsten Stichtags (Wer, Was und Wann)
          content:
            application/json:    
              schema:
                $ref: "#/components/schemas/Fecha"
              example:
                fecha: 2021-07-12
                quien: La AGETIC en coordinación con las entidades del sector público
                que: debe realizar la evaluación al proceso de implementación de
                  Software Libre y Estándares Libres, para considerar el estado de la
                  situación y el nivel de cumplimiento de los aspectos técnicos,
                  financieros administrativos y normativos a efectuar los ajustes
                  necesarios, producto de la evaluación
  /fechas-pasadas:
    get:
      summary: Liste der vergangenen Stichtage
      operationId: fechas_pasadas
      responses:
        '200':
          description: Die Daten der vergangenen Stichtage
          content:
            application/json:    
              schema:
                $ref: "#/components/schemas/Fechas"
              example:
                - fecha: 2018-07-12
                  quien: Las Entidades Públicas
                  que: debían enviar a la AGETIC el Plan Institucional de Implementación
                    de Gobierno Electrónico aprobado por la Máxima Autoridad Ejecutiva,
                    para su validación, seguimiento de su aplicación y publicación en su
                    página web
                - fecha: 2019-01-12
                  quien: Las Entidades Públicas
                  que: debían enviar a la AGETIC el Plan Institucional de Implementación
                    de Software Libre y Estándares Abiertos aprobado por la Máxima
                    Autoridad Ejecutiva, para su validación, seguimiento de su aplicación
                    y publicación en su página web
components:
  schemas:
    Fecha:
      type: object
      required:
        - fecha
        - quien
        - que
      properties:
        fecha:
          type: string
          format: date
        quien:
          type: string
        que:
          type: string
    Fechas:
      type: array
      items:
        $ref: "#/components/schemas/Fecha"

Diese Beschreibung enthält eine Referenz zur Implementiereung in Python (operationId), aber auch Beispielantworten (example).

Starten der REST-Schnittstellle

Da wir noch nichts implementiert haben, starten wir unseren Server zunächst in dem Mock-Modus. So werden die Antworten, das, was im der Beschreibung der Schnittstelle als example angegeben wurde.

   (venv) $ connexion run pislea-v1.yaml --mock=all

Wenn wir mit dem Browser dann die zwei Adressen besuchen, erhalten wir die beschriebenen Beispielantworten:

Der nächste Stichtag

Liste der vergangenen Stichtage

Ausblick

Das ist nur ein Bruchteil dessen, was mit OpenAPI und Connexion möglich ist. Im nächsten Beitrag, in ca. vier Wochen, werde ich die REST-Schnittstelle mit den Enpoints zu Ausschreibungsdaten im Boliviens Plan zur Implementierung von Freier Software und offenen Standards und diese dann mit dem Django REST Framework implementieren.

Anschließend werde ich, wahrscheinlich erst in Dezember, die Anwendung von HTTPie zeigen, um Listen und Details der Ausschreibungen zu bekommen.