4.4.1 EndpointExtension

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();
        }
    }


}