Diese API dient dem Zugriff auf die neu entwickelte Preis- und Produktdatenbank für Audio, die vom mediaservice wasmuth erstellt wurde.

Die Authentifizierung erfolgt über Access-Tokens, die über die üblichen Standards wie OAuth2 bzw. OpenID Connect abgerufen werden.

Es gibt einen "Nur-Lese" und "Schreiben"-Bereich. Die Versionsnummern für den reine Lesebereich laufen von 1.0 bis 4.9, der Schreib-Bereich hat die Versionsnummern >= 5.0
Für Third-Party Clients wird eine eingeschränkte Anzahl an Endpunkten bereitgestellt, deren Versionsnummern im Bereich 5.0 bis 5.9 liegen.

Im Schreib-Bereich gibt es im Wesentlichen Endpunkte für das

• Abrufen eines vermarkterspezifischen Jahrespaketes pro Sender
• Löschen eines vermarkterspezifischen Jahrespaketes
• Validieren eines solchen Jahrespaketes vor dem Upload
• Hochladen veränderter / neuer Jahrespakte pro Sender
• Veröffentlichen eines vermarkterspezifischen Jahrespaketes

Das grundlegende Design folgt dem bekannten REST Schema, wobei dieses auf eine pragmatische Weise umgesetzt wurde.
Weil im Lesebereich der Fokus auf den Abruf von zusammenhängenden Datenpaketen pro Sender ( Tarifjahr / Preisliste ) liegt, wurde zunächst auf die Implementierung von zahlreichen, feingranularen Endpunkten für jede einzelne Ressource ( z. Bsp. ein einzelner Preis ) verzichtet.

Ein Fokus wurde auf möglichst schlanke Datenmodelle gelegt. So hat beispielsweise das komplette Senderobjekt für ein Jahr
(Endpunkt /Sender{id}?jahr=xxxx) typischerweise deutlich weniger als 50 kByte. Wenn es für einen Sender viele Preiszonen inklusive unterschiedlicher Preise für jeden Wochentag gibt, können es aber auch 300 kByte werden.
Die zurückgegebenen Objekte sind strukturmäßig recht nahe am darunterliegenden Datenbankschema, auf eine Denormalisierung wurde weitgehend verzichtet.
Sollten die Beschreibungen für die verwendeten Typen- / Schlüssel benötigt werden, können diese leicht über die entsprechenden Endpunkte /Typen/* abgerufen werden.

Generell werden bei der Serialisierung ins JSON-Format Eigenschaften / Felder ohne Werte ( NULL ) nicht mit ausgegeben ( NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore )
Datums- / Zeitformate entsprechen ISO 8691, zulässige Werte sind also JJJJ-MM-ddThh:mm:ss (2020-02-05T23:04:42).
Die Benennung folgt dem camelCase-Schema, der erste Buchstabe jeder Benennung ist also jeweils kleingeschrieben.

Die genauen Feldbschreibungen ( Datentyp, Erforderlich [ja / nein], Länge von Zeichenketten und Beispiel-Daten) sind derzeit nur innerhalb der Service-Definition abrufbar.
Eine kurze Einführung findet sich unter dem Punkt Swagger-UI

Über entsprechende Request-Header beim API-Aufruf kann bei vielen Endpunkten eine Komprimierung der übertragenen Daten angefordert werden.
Unterstütze Kompressionsmethoden sind derzeit GZip und Brotli.

Als Übertragungsprotokoll wird bereits auf das neue HTTP/2 gesetzt. Für die SSL-Verschlüsselung wird mindestens TLS-Version 1.2 vorausgesetzt.

Nach der "reinen" Lehre würde man das Service-Level nur als Stufe 2 einordnen können, weil weitgehend auf die Implementierung von HATEOAS verzichtet wurde.

An einigen Endpunkten, bei denen es sinnvoll ist, wurde jedoch eine ultra leichtgewichtige Version dieses Prinzips implementiert. So gibt es bei den Zeiträumen eine Auflistung, wieviele Daten jeweils pro Kategorie (Preise / Termine / Zuschläge etc.) vorhanden sind. Anhand dieser Information kann anschließend gezielt diese Kategorie abgerufen werden: /Sender/{senderId}/Zeitraeume/{zeitraumId}?kategorien={kategorie}

Durch das Ressourcen basierte Adressierungsschema und die begrenzte Anzahl an implementierten Endpunkten ergeben sich aber auch nur bestimmte Möglichkeiten für Auflistungen / Suchen nach solchen Ressourcen.

So ist also bspw. die Suche nach Sendern über den Namen ( /Sender?Suchbegriff=* ) ebenso möglich, wie über den Vermarkter ( /Vermarkter?Suchbegriff=* und anschließend /Vermarkter/{id}/Sender ). Auch lassen sich Sender über Gebietskennziffern bzw. Orte und Gemeinden finden ( /Typen/Orte?Suchbegriff=* )

Allerdings gibt es momentan keine direkte Möglichkeit nach Sendern mit einem bestimmten Musikformat, einer Zielgruppe usw. zu suchen. Sollten solcherlei Funktionen gewünscht werden, müssen diese extra beauftragt und implementiert werden.

Bei einigen Auflistungen werden die zurückgegebenen Ergebnisse ggfs. auf eine maximale Anzahl begrenzt ( Server Side Paging ). Hierzu dienen dann jeweils die optionalen Angaben Seite und Seitengroesse. In der Swagger-UI lassen sich die jeweiligen zulässigen Werte einsehen. Wenn die übergebenen Werte nicht innerhalb des zulässigen Bereiches liegen, wird die Ergebnismenge auf den jeweiligen Standardwert begrenzt. Informationen zum Paging werden im Response-Header X-Pagination zurückgeliefert. Hier wird ein Json-Fragment in der folgen Struktur zurück gegeben:

{"total":949,"seitenGroesse":100,"aktuelleSeite":5,"seiten":10}