Starter kit per la pubblicazione su API interoperabili

Questo repository contiene una guida per la scrittura di API interoperabili.

Progetti associati:

• API Starter Kit per Java

• API Starter Kit per Python

• API Starter Kit per Go sperimentale

• API Starter Kit per C#- ASP.NET sperimentale

• Schemi riusabili per specifiche OAS3

• Validatore per specifiche OAS3

Materiale, slide, e webinar:

• Using OpenAPI to standardize the Italian API ecosystem slide (en, video)
• Design secure APIs (en) slide
• Design secure APIs (en, short) slide
• Videointervista e demo di API OAS Checker (en) video
• Community lab su API design e API canvas slide video
• Articolo medium

API e semantica:

• Self-explaining APIs, 2022 (en) slide
• Catalogo nazionale dati per l'interoperabilità semantica: https://schema.gov.it

API e standards:

• Extending HTTP for fun and non-profit (en) slide
• Interoperability rules for an European API Ecosystem (en)slide

Contenuto

• Un progetto di esempio in python
• Una directory openapi dove scrivere le specifiche, che include script e suggerimenti

Istruzioni

Gli step per la creazione di API interoperabili sono:

1. scrivere le specifiche in formato OpenAPI v3 partendo dagli esempi in openapi;

2. scrivere o generare il codice a partire dalle specifiche. Gli esempi per python e java che trovate nei progetti associati funzionano nativamente in formato OAS3 usando swagger-codegen-cli. Linguaggi meno diffusi o altri tool possono essere legati ancora a swagger (openapi v2). Nella directory scripts ci sono dei tool di conversione basati su docker.

3. scrivere i metodi dell'applicazione

Scrivere le specifiche

TBD

Convertire tra vari formati

La directory scripts contiene dei tool per convertire tra vari formati. Prima di convertire le specifiche bisogna verificare che non ci siano riferimenti esterni.

    # Generare delle specifiche swagger a partire da openapi.
    ./scripts/openapi2swagger.sh openapi/simple.yaml > /tmp/swagger.yaml

Effettuare il bundle di una specifica

Per agevolare la scrittura delle specifiche è possibile utilizzare feature come:

• yaml anchors
• json $references

Per consolidare le specifiche in un singolo file, autonomamente spendibile, è possibile creare un bundle col comando:

python -m openapi_resolver my-spec.yaml

In questo repository, per chiarezza, i file di specifica che utilizzano yaml anchors e $ref hanno estensione yaml.src.

Notate che questi file sono formalmente corretti e specifiche valide a tutti gli effetti. La creazione di un bundle viene effettuata solamente per una maggiore portabilità del risultato.

Generare il codice del server con swagger-codegen

Degli esempi di generazione di codice (o creazione degli stub) tramite swagger-codegen e swagger-codegen-cli sono presenti nei Makefile degli starter kit di Java e Python.

• https://github.com/teamdigitale/api-starter-kit-java/blob/master/Makefile
• https://github.com/teamdigitale/api-starter-kit-python/blob/master/Makefile

Il generatore non sovrascrive i file contenuti in .swagger-codegen-ignore.

API nativamente OAS3 (senza stub)

La libreria python Connexion basata su Flask e aiohttp permette anche di implementare direttamente i metodi associati agli endpoint senza necessariamente passare dalla generazione di codice.

• un esempio completo di API native in OAS3 che si autenticano con uno SPID IDP di test. Per fare il build dei container con l'IDP e l'API lanciare:

  make python-flask-spid
  

  Le applicazioni verranno servite sugli IP dei container docker, che e' possibile individuare utilizzando

  docker inspect --format '{{.Name}} {{.NetworkSettings.IPAddress}} {{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' [ELENCO DEI CONTAINER]
  

  Se l'API non trova l'IDP, basta ricrearlo con:

  docker-compose up -d idp 
  

Requisiti

Docker e Python 3.6+

Testare e scaricare le dipendenze con:

    tox