4.4 Bygge eget API med Flask

Nå er det du som er restauranten

So langt har du vært gjesten – du har brukt API-er andre har laget. Nå snur vi rollene: du skal bygge ditt eget API. Verktøyet er Flask, et enkelt og populært Python-rammeverk for webutvikling. Med Flask kan du lage REST API-er, definere endepunkter, håndtere GET, POST, PUT og DELETE, og returnere JSON-data.

Flask er ikke en del av standard Python, så du installerer det med pip install flask. Det kalles et mikroframework, fordi det er minimalistisk og lett å komme i gang med, men kan utvides med plugins ved behov. Din aller første Flask-app er kort:

from flask import Flask
app = Flask(__name__)

@app.route('/')
def hjem():
    return 'Velkommen til mitt API!'

@app.route('/hei/<navn>')
def hei(navn):
    return f'Hei, {navn}!'

if __name__ == '__main__':
    app.run(debug=True, port=5000)

Her er @app.route() en dekoratør som knytter en URL-sti til funksjonen under. <navn> er en URL-parameter, så /hei/Emma gir «Hei, Emma!». Og debug=True gir bedre feilmeldinger og automatisk omstart mens du utvikler.

JSON, ruter og forespørsler

Å returnere ren tekst er greit for læring, men et ekte API returnerer JSON. Til det bruker vi jsonify, som automatisk konverterer Python-objekter til en JSON-respons med riktige HTTP-headere:

from flask import Flask, jsonify

@app.route('/api/elever')
def elever():
    data = [{'id': 1, 'navn': 'Emma'}, {'id': 2, 'navn': 'Lars'}]
    return jsonify(data)

En rute er en URL-sti Flask lytter på, og du kan styre hvilke HTTP-metoder den godtar med methods=['GET'] eller methods=['POST']. Standard er GET hvis du ikke sier noe annet.

For å lese data fra forespørselen bruker vi request-objektet. Query-parametere fra URL-en, som /sok?q=flask&limit=5, hentes med request.args.get('q', '') – det andre argumentet er en standardverdi, og du kan legge til type=int for å konvertere. Når en klient sender data i kroppen av en POST, leser du den med request.get_json(). Da bør du alltid validere: hvis dataene mangler eller en nødvendig nøkkel ikke finnes, returnerer du en feilmelding med statuskode 400. Lykkes opprettelsen, returnerer du den nye ressursen med statuskode 201 (Created). Legg merke til at du i Flask kan returnere både data og en statuskode samtidig: return jsonify(ny_elev), 201.

Et komplett CRUD-API

Nå kan vi sette sammen alt til et fullstendig CRUD-API – Create, Read, Update, Delete – med de fire HTTP-metodene. Tenk på et bok-API med en liste bøker i minnet. Create er en POST til /api/boker som leser inn JSON, validerer at tittel finnes, lager en ny bok med ny id og returnerer den med 201. Read har to varianter: GET til /api/boker returnerer alle, mens GET til /api/boker/<int:bok_id> finner én bestemt og returnerer 404 hvis den ikke finnes. Update er en PUT til /api/boker/<int:bok_id> som oppdaterer feltene på en eksisterende bok. Delete er en DELETE som fjerner boken fra listen.

Legg merke til to mønstre som går igjen. Ruteparameteren <int:bok_id> forteller Flask at id-en skal tolkes som et heltall. Og for å finne et element bruker vi next((b for b in bøker if b['id'] == bok_id), None), som returnerer den første treffende boken eller None.

Du kan teste ditt eget API med requests-biblioteket du allerede kjenner. requests.get('http://localhost:5000/api/boker') henter alle, requests.post(url, json=ny_bok) oppretter, requests.put(url, json=oppdatering) endrer, og requests.delete(url) sletter. Slik kan du automatisere testingen. Et praktisk eksempel er et værlogg-API der POST registrerer observasjoner med tidsstempel, GET henter dem (eventuelt begrenset med en limit-parameter), og et eget statistikk-endepunkt regner ut gjennomsnitt, min og max av temperaturene.

Oppsummering

Vi snudde rollene og ble serveren selv. Flask er et mikroframework der @app.route() knytter URL-stier til funksjoner, og <navn>-deler fanger URL-parametere. Et ekte API returnerer JSON med jsonify, godtar bestemte HTTP-metoder via methods=[...], og leser data med request.args.get() for query-parametere og request.get_json() for POST-kropp – alltid med validering og passende statuskoder som 400 og 201.

Satt sammen ble dette et komplett CRUD-API: POST for å opprette, GET for å lese (alle eller én), PUT for å oppdatere og DELETE for å slette, med <int:id>-parametere og 404 når noe ikke finnes. Du kan teste hele API-et med requests-biblioteket. I neste kapittel ser vi på det som ligger under det hele: nettverkskommunikasjon.