Dient zum Bereitstellen von REST-Endpoints
Allgemeines
Dieser Extension Point erlaubt das Bereitstellen von eigenen REST-Endpunkten, um so die Standard-Endpunkte von SmartMES zu erweitern.
Unter
http://api.bluebiz.de/smartmes
gibt es einige Informationen, die hauptsächlich den externen Zugriff beschreiben.
Alle Endpoints werden unterhalb von
/api/{plugin-id}/
eingebunden, wobei "plugin-id" die jeweilige Unique-ID des Plugins ist.
Gibt es also eine Mapping-URL "/orders" im Plugin mit der ID "example-plugin", so ergibt dies folgenden Endpoint:
/api/example-plugin/orders
Endpunkte Definieren
Endpunkte können als GET, POST, DELETE und PUT definiert werden.
Zum Definieren eines Endpunktes, müssen innerhalb der Implementierung von EndpointExtension Methoden definiert werden, die dann mit @EndpointMapping annotiert werden.
@EndpointMapping benötigt dabei die Mapping-URL als "value" und ggf. einen Methoden-Typ (GET, POST, DELETE, PUT)
Die Methode, die den Endpunkt beschreibt, muss "EndpointResult" zurückliefern. Ein EndpointResult definiert im Wesentlichen den HTTP-Status-Code (z.B. 200 ist "OK" oder 404 ist "nicht gefunden") und kann ggf. eine Objekt oder eine Liste als Ergebnis beinhalten (der Response-Body).
Der Response-Body, der innerhalb von EndpointResult zurückgegeben wird, muss serialisierbar sein. Hierzu wird im Hintergrund Jackson eingesetzt und konvertiert das Objekt in eine JSON-Darstellung.
GET-Methode
Antwortet auf http-GET Anfragen.
Die Mapping-URL kann dabei Parameter enthalten. Im zweiten Fall wird z.B. eine "id" als URL-Parameter erwartet, so dass hier der Aufruf "/api/example-plugin/orders/323" wäre
@Extension public class ExamplePluginEndpoint implements EndpointExtension { @EndpointMapping("/orders") public EndpointResult<?> getProductionOrders() throws ServiceException { List<ProductionOrderADO> result = SmartMES.getService().productionOrderService().getProductionOrders(); if (result != null) { return EndpointResult.ok(result); } else { return EndpointResult.notFound(); } } @EndpointMapping(value = "/orders/{id}", method = EndpointType.GET) public EndpointResult<?> getProductionOrder(Long id) throws ServiceException { //... } }
POST/PUT-Methode
Antwortet auf http-POST-Anfragen und nimmt entsprechend ein POST-Request-Body entgegen.
Der Inhalt der POST-Anfrage wird dabei von Jackson deserialisiert und an die Methode übergeben. Hier wird z.B. ein Objekt "ProductionOrderADO" als POST übergeben.
@Extension public class ExamplePluginEndpoint implements EndpointExtension { @EndpointMapping(value = "/orders", method = EndpointType.POST) public EndpointResult<?> createProductionOrder(ProductionOrderADO data) throws ServiceException { String number = data.getNumber(); //... } }
PUT-Methode
Antwortet auf http-PUT-Anfragen und nimmt entsprechend ein PUT-Request-Body entgegen.
Der Inhalt der PUT-Anfrage wird dabei von Jackson deserialisiert und an die Methode übergeben. Hier wird z.B. ein Objekt "ProductionOrderADO" als POST übergeben.
@Extension public class ExamplePluginEndpoint implements EndpointExtension { @EndpointMapping(value = "/orders/{id}", method = EndpointType.POST) public EndpointResult<?> updateProductionOrder(ProductionOrderADO ado, Long id) throws ServiceException { //... replace order with id with ado } }
DELETE-Methode
Antwortet auf http-DELETE Anfragen.
Die Mapping-URL kann dabei Parameter enthalten. Im zweiten Fall wird z.B. eine "id" als URL-Parameter erwartet, so dass hier der Aufruf "/api/example-plugin/orders/323" wäre
@Extension public class ExamplePluginEndpoint implements EndpointExtension { @EndpointMapping(value = "/orders/{id}", method = EndpointType.DELETE) public EndpointResult<?> deleteProductionOrder(Long id) throws ServiceException { //... remove production order with matching id } }
Verwenden
Verwenden in einer View
Innerhalb einer View (siehe auch 4.3. Plugins - Views), kann dies dann z.B. mit dem endpoint-Service abgefragt werden:
smartmes.view(function (smartMES, $scope) { // fetch orders from example-plugin smartMES.endpoint.get('/orders').then(function(result){ $scope.orders = result.data.orders; }); });
Alternativ kann auch der $http-Service wie folgt verwendet werden:
smartmes.view(function (smartMES, $scope) { // fetch orders from example-plugin smartMES.http.get('/api/example-plugin/orders').then(function(result){ $scope.orders = result.data.orders; }); });
Die SmartMES-View sorgt dabei automatisch für den richtigen Login.
Verwendung von Extern
Läuft smartMES z.B. unter localhost:9090, so ist der Endpunkt unter
http://localhost:9090/api/example-plugin/orders
erreichbar.
Von Extern ist im Vergleich zum internen Aufruf jedoch ein Login erforderlich.
Beispiel
@Extension public class ExamplePluginEndpoint implements EndpointExtension { @EndpointMapping(value = "/orders", method = EndpointType.GET) public EndpointResult<?> getProductionOrders() throws ServiceException { List<ProductionOrderADO> result = SmartMES.getService().productionOrderService().getProductionOrders(); if (result != null) { return EndpointResult.ok(result); } else { return EndpointResult.notFound(); } } @EndpointMapping(value = "/orders/{id}", method = EndpointType.GET) public EndpointResult<?> getProductionOrder(Long id) throws ServiceException { ProductionOrderADO result = SmartMES.getService().productionOrderService().getProductionOrder(id); if (result != null) { return EndpointResult.ok(result); } else { return EndpointResult.notFound(); } } }
Kommentare
0 Kommentare
Bitte melden Sie sich an, um einen Kommentar zu hinterlassen.