So erstellen Sie eine JSON-API mit Python

Die JSON-API-Spezifikation ist eine leistungsstarke Möglichkeit, die Kommunikation zwischen Client und Server zu ermöglichen. Es gibt die Struktur der Anforderungen und Antworten an, die zwischen den beiden im JSON-Format gesendet werden.

Als Datenformat bietet JSON den Vorteil, dass es leicht und lesbar ist. Dies macht es sehr einfach, schnell und produktiv damit zu arbeiten. Die Spezifikation soll die Anzahl der Anforderungen und die Datenmenge minimieren, die zwischen Client und Server gesendet werden muss.

Hier erfahren Sie, wie Sie mit Python und Flask eine grundlegende JSON-API erstellen. Im weiteren Verlauf des Artikels erfahren Sie, wie Sie einige der Funktionen der JSON-API-Spezifikation ausprobieren können.

Flask ist eine Python-Bibliothek, die ein "Mikro-Framework" für die Webentwicklung bietet. Es eignet sich hervorragend für eine schnelle Entwicklung, da es über eine einfache, aber erweiterbare Kernfunktionalität verfügt.

Ein wirklich einfaches Beispiel für das Senden einer JSON-ähnlichen Antwort mit Flask ist unten dargestellt:

from flask import Flask app = Flask(__name__) @app.route('/') def example(): return '{"name":"Bob"}' if __name__ == '__main__': app.run()

In diesem Artikel werden zwei Add-Ons für Flask verwendet:

  • Flask-REST-JSONAPI hilft bei der Entwicklung einer API, die der JSON-API-Spezifikation genau folgt.
  • Flask-SQLAlchemy verwendet SQLAlchemy, um das Erstellen und Interagieren mit einer einfachen Datenbank sehr einfach zu gestalten.

Das große Bild

Das Endziel besteht darin, eine API zu erstellen, die eine clientseitige Interaktion mit einer zugrunde liegenden Datenbank ermöglicht. Zwischen der Datenbank und dem Client befinden sich mehrere Ebenen - eine Datenabstraktionsschicht und eine Ressourcenmanagerebene.

Hier ist eine Übersicht über die Schritte:

  1. Definieren Sie eine Datenbank mit Flask-SQLAlchemy
  2. Erstellen Sie eine Datenabstraktion mit Marshmallow-JSONAPI
  3. Erstellen Sie Ressourcenmanager mit Flask-REST-JSONAPI
  4. Erstellen Sie URL-Endpunkte und starten Sie den Server mit Flask

In diesem Beispiel wird ein einfaches Schema verwendet, das moderne Künstler und ihre Beziehungen zu verschiedenen Kunstwerken beschreibt.

Installieren Sie alles

Bevor Sie beginnen, müssen Sie das Projekt einrichten. Dazu müssen Sie einen Arbeitsbereich und eine virtuelle Umgebung erstellen, die erforderlichen Module installieren und die wichtigsten Python- und Datenbankdateien für das Projekt erstellen.

Erstellen Sie über die Befehlszeile ein neues Verzeichnis und navigieren Sie hinein.

$ mkdir flask-jsonapi-demo $ cd flask-jsonapi-demo/

Es wird empfohlen, für jedes Ihrer Python-Projekte virtuelle Umgebungen zu erstellen. Sie können diesen Schritt überspringen, er wird jedoch dringend empfohlen.

$ python -m venv .venv $ source .venv/bin/activate 

Sobald Ihre virtuelle Umgebung erstellt und aktiviert wurde, können Sie die für dieses Projekt erforderlichen Module installieren.

$ pip install flask-rest-jsonapi flask-sqlalchemy

Alles, was Sie benötigen, wird als Voraussetzung für diese beiden Erweiterungen installiert. Dies schließt Flask selbst und SQLAlchemy ein.

Der nächste Schritt besteht darin, eine Python-Datei und -Datenbank für das Projekt zu erstellen.

$ touch application.py artists.db

Erstellen Sie das Datenbankschema

Hier beginnen Sie mit der Änderung application.py, um das Datenbankschema für das Projekt zu definieren und zu erstellen.

Öffnen Sie application.pyin Ihrem bevorzugten Texteditor. Beginnen Sie mit dem Importieren einiger Module. Aus Gründen der Übersichtlichkeit werden Module unterwegs importiert.

Erstellen Sie als Nächstes ein Objekt, das appals Instanz der Flask-Klasse aufgerufen wird .

Verwenden Sie danach SQLAlchemy, um eine Verbindung zu der von Ihnen erstellten Datenbankdatei herzustellen. Der letzte Schritt besteht darin, eine Tabelle mit dem Namen zu definieren und zu erstellen artists.

from flask import Flask from flask_sqlalchemy import SQLAlchemy # Create a new Flask application app = Flask(__name__) # Set up SQLAlchemy app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:////artists.db' db = SQLAlchemy(app) # Define a class for the Artist table class Artist(db.Model): id = db.Column(db.Integer, primary_key=True) name = db.Column(db.String) birth_year = db.Column(db.Integer) genre = db.Column(db.String) # Create the table db.create_all()

Erstellen einer Abstraktionsschicht

Der nächste Schritt verwendet das Marshmallow-JSONAPI-Modul, um eine logische Datenabstraktion über die gerade definierten Tabellen zu erstellen.

Der Grund für die Erstellung dieser Abstraktionsschicht ist einfach. Sie haben mehr Kontrolle darüber, wie Ihre zugrunde liegenden Daten über die API verfügbar gemacht werden. Stellen Sie sich diese Ebene als eine Linse vor, durch die der API-Client die zugrunde liegenden Daten klar und nur die Bits anzeigen kann, die er sehen muss.

Im folgenden Code wird die Datenabstraktionsschicht als eine Klasse definiert, die von der Marshmallow-JSONAPI- SchemaKlasse erbt . Über die API wird auf einzelne Datensätze und mehrere Datensätze aus der Künstlertabelle zugegriffen.

Innerhalb dieses Blocks Metadefiniert die Klasse einige Metadaten. Insbesondere lautet der Name des URL-Endpunkts für die Interaktion mit einzelnen Datensätzen artist_one, wobei jeder Künstler durch einen URL-Parameter identifiziert wird . Der Name des Endpunkts für die Interaktion mit vielen Datensätzen lautet artist_many.

Die verbleibenden definierten Attribute beziehen sich auf die Spalten in der Künstlertabelle. Hier können Sie weiter steuern, wie jeder über die API verfügbar gemacht wird.

Wenn Sie beispielsweise POST-Anforderungen zum Hinzufügen neuer Künstler zur Datenbank stellen, können Sie namedurch Festlegen sicherstellen, dass das Feld obligatorisch ist required=True.

Und wenn Sie aus irgendeinem Grund nicht möchten, dass das birth_yearFeld bei GET-Anforderungen zurückgegeben wird, können Sie dies durch Festlegen angeben load_only=True.

from marshmallow_jsonapi.flask import Schema from marshmallow_jsonapi import fields # Create data abstraction layer class ArtistSchema(Schema): class Meta: type_ = 'artist' self_view = 'artist_one' self_view_kwargs = {'id': ''} self_view_many = 'artist_many' id = fields.Integer() name = fields.Str(required=True) birth_year = fields.Integer(load_only=True) genre = fields.Str() 

Erstellen Sie Ressourcenmanager und URL-Endpunkte

The final piece of the puzzle is to create a resource manager and corresponding endpoint for each of the routes /artists and /artists/id.

Each resource manager is defined as a class that inherits from the Flask-REST-JSONAPI classes ResourceList and ResourceDetail.

Here they take two attributes. schema is used to indicate the data abstraction layer the resource manager uses, and data_layer indicates the session and data model that will be used for the data layer.

Next, define api as an instance of Flask-REST-JSONAPI's Api class, and create the routes for the API with api.route(). This method takes three arguments - the data abstraction layer class, the endpoint name, and the URL path.

The last step is to write a main loop to launch the app in debug mode when the script is run directly. Debug mode is great for development, but it is not suitable for running in production.

# Create resource managers and endpoints from flask_rest_jsonapi import Api, ResourceDetail, ResourceList class ArtistMany(ResourceList): schema = ArtistSchema data_layer = {'session': db.session, 'model': Artist} class ArtistOne(ResourceDetail): schema = ArtistSchema data_layer = {'session': db.session, 'model': Artist} api = Api(app) api.route(ArtistMany, 'artist_many', '/artists') api.route(ArtistOne, 'artist_one', '/artists/') # main loop to run app in debug mode if __name__ == '__main__': app.run(debug=True)

Make GET and POST requests

Now you can start using the API to make HTTP requests. This could be from a web browser, or from a command line tool like curl, or from within another program (e.g., a Python script using the Requests library).

To launch the server, run the application.py script with:

$ python application.py

In your browser, navigate to //localhost:5000/artists.  You will see a JSON output of all the records in the database so far. Except, there are none.

To start adding records to the database, you can make a POST request. One way of doing this is from the command line using curl. Alternatively, you could use a tool like Insomnia, or perhaps code up a simple HTML user interface that posts data using a form.

With curl, from the command line:

curl -i -X POST -H 'Content-Type: application/json' -d '{"data":{"type":"artist", "attributes":{"name":"Salvador Dali", "birth_year":1904, "genre":"Surrealism"}}}' //localhost:5000/artists

Now if you navigate to //localhost:5000/artists, you will see the record you just added. If you were to add more records, they would all show here as well, as this URL path calls the artists_many endpoint.

To view just a single artist by their id number, you can navigate to the relevant URL. For example, to see the first artist, try //localhost:5000/artists/1.

Filtering and sorting

One of the neat features of the JSON API specification is the ability to return the response in more useful ways by defining some parameters in the URL. For instance, you can sort the results according to a chosen field, or filter based on some criteria.

Flask-REST-JSONAPI comes with this built in.

To sort artists in order of birth year, just navigate to //localhost:5000/artists?sort=birth_year. In a web application, this would save you from needing to sort results on the client side, which could be costly in terms of performance and therefore impact the user experience.

Filtering is also easy. You append to the URL the criteria you wish to filter on, contained in square brackets. There are three pieces of information to include:

  • "name" - the field you are filtering by (e.g., birth_year)
  • "op" - the filter operation ("equal to", "greater than", "less than" etc.)
  • "val" - the value to filter against (e.g., 1900)

For example, the URL below retrieves artists whose birth year is greater than 1900:

//localhost:5000/artists?filter=[{"name":"birth_year","op":"gt","val":1900}]

This functionality makes it much easier to retrieve only relevant information when calling the API. This is valuable for improving performance, especially when retrieving potentially large volumes of data over a slow connection.

Pagination

Another feature of the JSON API specification that aids performance is pagination. This is when large responses are sent over several "pages", rather than all in one go. You can control the page size and the number of the page you request in the URL.

So, for example, you could receive 100 results over 10 pages instead of loading all 100 in one go. The first page would contain results 1-10, the second page would contain results 11-20, and so on.

To specify the number of results you want to receive per page, you can add the parameter ?page[size]=X to the URL, where X is the number of results. Flask-REST-JSONAPI uses 30 as the default page size.

To request a given page number, you can add the parameter ?page[number]=X, where is the page number. You can combine both parameters as shown below:

//localhost:5000/artists?page[size]=2&page[number]=2

This URL sets the page size to two results per page, and asks for the second page of results. This would return the third and fourth results from the overall response.

Relationships

Almost always, data in one table will be related to data stored in another. For instance, if you have a table of artists, chances are you might also want a table of artworks. Each artwork is related to the artist who created it.

The JSON API specification allows you to work with relational data easily, and the Flask-REST-JSONAPI lets you take advantage of this. Here, this will be demonstrated by adding an artworks table to the database, and including relationships between artist and artwork.

To implement the artworks example, it will be necessary to make a few changes to the code in application.py.

First, make a couple of extra imports, then create a new table which relates each artwork to an artist:

from marshmallow_jsonapi.flask import Relationship from flask_rest_jsonapi import ResourceRelationship # Define the Artwork table class Artwork(db.Model): id = db.Column(db.Integer, primary_key=True) title = db.Column(db.String) artist_id = db.Column(db.Integer, db.ForeignKey('artist.id')) artist = db.relationship('Artist', backref=db.backref('artworks'))

Next, rewrite the abstraction layer:

# Create data abstraction class ArtistSchema(Schema): class Meta: type_ = 'artist' self_view = 'artist_one' self_view_kwargs = {'id': ''} self_view_many = 'artist_many' id = fields.Integer() name = fields.Str(required=True) birth_year = fields.Integer(load_only=True) genre = fields.Str() artworks = Relationship(self_view = 'artist_artworks', self_view_kwargs = {'id': ''}, related_view = 'artwork_many', many = True, schema = 'ArtworkSchema', type_ = 'artwork') class ArtworkSchema(Schema): class Meta: type_ = 'artwork' self_view = 'artwork_one' self_view_kwargs = {'id': ''} self_view_many = 'artwork_many' id = fields.Integer() title = fields.Str(required=True) artist_id = fields.Integer(required=True) 

This defines an abstraction layer for the artwork table, and adds a relationship between artist and artwork to the ArtistSchema class.

Next, define new resource managers for accessing artworks many at once and one at a time, and also for accessing the relationships between artist and artwork.

class ArtworkMany(ResourceList): schema = ArtworkSchema data_layer = {'session': db.session, 'model': Artwork} class ArtworkOne(ResourceDetail): schema = ArtworkSchema data_layer = {'session': db.session, 'model': Artwork} class ArtistArtwork(ResourceRelationship): schema = ArtistSchema data_layer = {'session': db.session, 'model': Artist}

Finally, add some new endpoints:

api.route(ArtworkOne, 'artwork_one', '/artworks/') api.route(ArtworkMany, 'artwork_many', '/artworks') api.route(ArtistArtwork, 'artist_artworks', '/artists//relationships/artworks')

Run application.py and trying posting some data from the command line via curl:

curl -i -X POST -H 'Content-Type: application/json' -d '{"data":{"type":"artwork", "attributes":{"title":"The Persistance of Memory", "artist_id":1}}}' //localhost:5000/artworks

This will create an artwork related to the artist with id=1.

In the browser, navigate to //localhost:5000/artists/1/relationships/artworks. This should show the artworks related to the artist with id=1. This saves you from writing a more complex URL with parameters to filter artworks by their artist_id field. You can quickly list all the relationships between a given artist and their artworks.

Another feature is the ability to include related results in the response to calling the artists_one endpoint:

//localhost:5000/artists/1?include=artworks

This will return the usual response for the artists endpoint, and also results for each of that artist's artworks.

Sparse Fields

One last feature worth mentioning - sparse fields. When working with large data resources with many complex relationships, the response sizes can blow up real fast. It is helpful to only retrieve the fields you are interested in.

The JSON API specification lets you do this by adding a fields parameter to the URL. For example URL below gets the response for a given artist and their related artworks. However, instead of returning all the fields for the given artwork, it returns only the title.

//localhost:5000/artists/1?include=artworks&fields[artwork]=title

This is again very helpful for improving performance, especially over slow connections. As a general rule, you should only make requests to and from the server with the minimal amount of data required.

Final remarks

The JSON API specification is a very useful framework for sending data between server and client in a clean, flexible format. This article has provided an overview of what you can do with it, with a worked example in Python using the Flask-REST-JSONAPI library.

So what will you do next? There are many possibilities. The example in this article has been a simple proof-of-concept, with just two tables and a single relationship between them. You can develop an application as sophisticated as you like, and create a powerful API to interact with it using all the tools provided here.

Thanks for reading, and keep coding in Python!