Grundlagen¶
Wenn Sie AaaS-API erfolgreich installiert haben, können Sie anfangen Ihre Projekte, Repositorien und Services anzulegen. Wenn Sie damit fertig sind, erstellt unsere Anwendung aus Ihren Projekten sowohl Datenbankschemata als auch entsprechende Programmierschnittstellen, die anschließend von Ihren API-Konsumenten benutzt werden können. Dabei sind eine Reihe von Besonderheiten zu beachten, die wir Ihnen im Folgenden näher bringen wollen.
Hinweis
Die Leistungsfähigkeit von AaaS-API im Entwicklungsmodus, insbesondere wenn der Applikationscache noch nicht generiert wurde oder aufgrund von Änderungen neu generiert werden muss, unterscheidet sich signifikant von der Leistungsfähigkeit im Produktivbetrieb. Während der Produktion sollten Sie APP_ENV in der .env-Datei unbedingt auf prod setzen. Lesen Sie mehr dazu im Abschnitt Deployment.
Endpunkt-Präfixe¶
Wir separieren die von Ihnen entworfene und von uns erstellte API von unserem System mittels URI-Präfixen. So können Sie unsere API-Ressourcen vor Ihren API-Konsumenten verbergen oder dereinst die Zugangsberechtigungen per Zugriffslisten (ACL) steuern.
| URI-Präfix | Definition |
| /aaas | Zugriff auf Ressourcen zur Generierung Ihrer API (Unser System) |
| /api | Zugriff auf Ressourcen der von uns generierten API (Ihr System) |
| /docs | Swagger, Swagger UI, ReDoc. (Deaktiviert im Produktivbetrieb) |
| /auth | Endpunkt für Authentifizierung |
HTTP-Clients¶
Um sich mit AaaS-API vertraut zu machen und Anfragen an die API-Endpunkte zu stellen, können Sie einen HTTP-Client Ihrer Wahl benutzen. Im Prinzip reicht dafür schon das Kommandozeilen-Programm cURL. Wir empfehlen Postman oder die Chrome-Erweiterung Restlet-Client. Wenn Sie AaaS-API innerhalb Ihrer Entwicklungsumgebung benutzen, sodass die Umgebungsvariable APP_ENV in der .env-Datei auf dev gesetzt ist, dann können Sie auch Swagger UI benutzen. Rufen Sie dafür einfach https://localhost/docs in Ihrem Browser auf.
HTTP-Header¶
Unser System kann API-Ressourcen in unterschiedlichen Formaten serialisieren und deserialisieren. So unterstützen wir neben JavaScript Object Notation (JSON) auch JavaScript Object Notation für verlinkte Daten (JSON-LD). Eventuell werden wir in Zukunft weitere Formate anbieten. Je nachdem, in welchen Format Sie Ihre Anfragen stellen oder in welchem Format Sie unsere Antworten erwarten, müssen Sie entweder einen HTTP-Header bei der Anfrage mitschicken oder einen Format-Suffix an die entsprechende API-URI anhängen.
| HTTP-Header | Wert | Definition |
| Accept | application/json | Ihr HTTP-Client erwartet JSON. Unsere API antwortet im JSON-Format. |
| Content-Type | application/json | Unsere API erwartet valides JSON. Sie schicken im HTTP-Request-Body valides JSON. |
Als Alternative dazu können Sie auch einen Suffix anhängen, der das Ausgabeformat spezifiziert:
HTTP_METHOD SCHEME ":" //HOST/PREFIX/PATH.json # ".json" ist der Suffix.
Der API-Server antwortet dann im JSON-Format.
HTTP-Requests¶
Wenn Sie AaaS-API ohne unsere grafische Benutzeroberfläche verwenden oder wenn Sie eine eigene Benutzeroberfläche entwickeln möchten, dann müssen Sie sich mit unseren API-Endpunkten vertraut machen. Bei unseren API-URIs gilt grundsätzlich, dass Sie mit Ihrem HTTP-Client die entsprechende HTTP-Methode angeben und anschließend eine HTTP-Anfrage an einen unserer Endpunkte stellen:
HTTP_METHOD SCHEME ":" //HOST/PREFIX/PATH.FORMAT [ "?" QUERY ]
Die von uns generierte und später von Ihren API-Konsumenten zu benutzende API beinhaltet zusätzlich noch den Namen des entsprechenden Repositoriums in der URI. So können Sie unter anderem Ihre Zugriffslisten filigraner gestalten:
HTTP_METHOD SCHEME ":" //HOST/PREFIX/REPOSITORY/PATH.FORMAT [ "?" QUERY ]
FORMAT und QUERY sind optional. Um sich eine Liste aller API-Projekte ausgeben zu lassen, könnten Sie folgende HTTP-GET-Anfrage stellen:
curl -X GET "https://localhost/aaas/projects" -H "accept: application/json"
Der API-Server gibt Ihnen dann die entsprechende Kollektion zurück:
[
{
"id": 1,
"name": "My Online Shop",
"description": "My fance online shop which uses AaaS.",
"repositories": [
"/aaas/project/repositories/1",
"/aaas/project/repositories/2"
]
}
]
Wenn Sie als Format-Suffix json angeben, dann müssen Sie den Accept-Header nicht mitsenden:
curl -X GET "http://localhost/aaas/projects.json"
Wenn Sie statt der Kollektion nur auf eine einzelne Ressource zugreifen möchten, dann müssen Sie noch einen eineindeutigen Schlüssel angeben, der für jede unserer und später auch Ihrer API-Ressourcen existiert:
curl -X GET "https://localhost/aaas/project/repositories/1" -H "accept: application/json"
{
"id": 1,
"name": "Blog",
"description": "Blog repository holds services for our blog.",
"services": [
"/aaas/repository/services/1",
"/aaas/repository/services/2",
"/aaas/repository/services/3"
]
}
curl -X GET "https://localhost/aaas/repository/services/1" -H "accept: application/json"
{
"id": 1,
"name": "Article",
"description": "Articles for our blog repository.",
"type": "list",
"repository": "/aaas/project/repositories/1",
"fields": [
"/aaas/service/fields/1",
"/aaas/service/fields/2"
]
}
curl -X GET "https://localhost/aaas/service_fields/1" -H "accept: application/json"
{
"id": 1,
"name": "title",
"description": "Title for our blog post.",
"dataType": "string",
"length": 255,
"isUnique": false,
"isNullable": false,
"dataTypePrecision": null,
"dataTypeScale": null,
"service": "/aaas/repository_services/1",
"options": [],
"assertions": [],
"relation": null
}
HTTP-Methoden¶
Unsere API stellt Ihnen applikationsübergreifend die HTTP-Methoden GET, PUT, POST und DELETE zur Verfügung.
| Methode | Definition |
| GET | Sie beziehen Ressourcen vom Server |
| POST | Sie legen eine Ressource auf dem Server an |
| PUT | Sie bearbeiten eine Ressource auf dem Server |
| DELETE | Sie löschen eine Ressource vom Server |
Eingebettete Ressourcen¶
Wie Ihnen sicherlich schon aufgefallen ist, serialisiert unser System eingebettete Ressourcen bzw. Relationen über dereferenzierbare IRIs. Sie müssen dementsprechend zusätzliche HTTP-Requests absetzen um Details der entsprechenden Objekte zu erhalten. Aus Gründen der Leistungsfähigkeit ist es allerdings manchmal sinnvoller zusätzliche HTTP-Requests zu vermeiden und stattdessen den API-Server anzuweisen die Details der entsprechenden Relationen ergänzend zu serialisieren. Sie können dafür von uns implementierte Serialisierungsgruppen benutzen. Für Projekte, Repositorien und deren Services geben wir Ihnen hier schon einmal einen kleinen Überblick. Sie erfahren mehr auf den nächsten Seiten.
| Gruppe | Erklärung |
| repository | Serialisiert repository-Attribute |
| service | Serialisiert service-Attribute |
Mit AaaS-API haben Sie später ebenfalls die Möglichkeit Serialisierungsgruppen zu erstellen und Ihren API-Konsumenten zur Verfügung zu stellen. In einigen Fällen ist Ihr System dann leistungsfähiger.
Beispiel¶
curl -X GET "https://localhost/aaas/projects/1?groups[]=repository&groups[]=service" -H "accept: application/json"
{
"id": 1,
"name": "My Online Shop",
"description": "My fance online shop which uses AaaS.",
"repositories": [
{
"id": 2,
"name": "Catalog",
"description": "Catalog repository holds services for our catalog.",
"services": [
{
"id": 4,
"name": "Product",
"description": "Products service for our catalog repository.",
"type": "list",
"fields": []
},
{
"id": 5,
"name": "Category",
"description": "Categories for our catalog repository.",
"type": "tree",
"fields": []
},
{
"id": 6,
"name": "ProductDetail",
"description": "Details for our products.",
"type": "list",
"fields": []
},
{
"id": 1,
"name": "Blog",
"description": "Blog repository holds services for our blog.",
"services": [
{
"id": 1,
"name": "Article",
"description": "Articles for our blog repository.",
"type": "list",
"fields": []
},
{
"id": 2,
"name": "Label",
"description": "Labels for our blog repository.",
"type": "list",
"fields": []
},
{
"id": 3,
"name": "Comment",
"description": "Comments for our blog repository.",
"type": "list",
"fields": []
}
]
}
]
}