pip_services3_rpc.services.RestService module

pip_services3_rpc.services.RestService

REST service implementation

copyright: Conceptual Vision Consulting LLC 2018-2019, see AUTHORS for more details.
license: MIT, see LICENSE for more details.

class pip_services3_rpc.services.RestService.RestService

Bases: pip_services3_commons.run.IOpenable.IOpenable, pip_services3_commons.config.IConfigurable.IConfigurable, pip_services3_commons.refer.IReferenceable.IReferenceable, pip_services3_commons.refer.IUnreferenceable.IUnreferenceable, pip_services3_rpc.services.IRegisterable.IRegisterable

Abstract service that receives remove calls via HTTP/REST protocol.

### Configuration parameters ###

base_route: base route for remote URI
dependencies:
- endpoint: override for HTTP Endpoint dependency
- controller: override for Controller dependency
connection(s):
- discovery_key: (optional) a key to retrieve the connection from IDiscovery
- protocol: connection protocol: http or https
- host: host name or IP address
- port: port number
- uri: resource URI or connection string with all parameters in it
credential - the HTTPS credentials:
- ssl_key_file: the SSL private key in PEM
- ssl_crt_file: the SSL certificate in PEM
- ssl_ca_file: the certificate authorities (root cerfiticates) in PEM

### References ###

*:logger:*:*:1.0 (optional) ILogger components to pass log messages
*:counters:*:*:1.0 (optional) ICounters components to pass collected measurements
*:discovery:*:*:1.0 (optional) IDiscovery services to resolve connection
*:endpoint:http:*:1.0 (optional) HttpEndpoint reference
*:tracer:*:*:1.0 (optional) ITracer components to record traces

Example:

class MyRestService(RestService):
    _controller = None
    # ...

    def __init__(self):
        super(MyRestService, self).__init__()
        self._dependencyResolver.put("controller", Descriptor("mygroup","controller","*","*","1.0"))

    def set_references(self, references):
        super(MyRestService, self).set_references(references)
        self._controller = self._dependencyResolver.get_required("controller")

    def register():
        # ...

service = MyRestService()
service.configure(ConfigParams.from_tuples("connection.protocol", "http",
                                               "connection.host", "localhost",
                                               "connection.port", 8080))
service.set_references(References.from_tuples(Descriptor("mygroup","controller","default","default","1.0"), controller))
service.open("123")

close(correlation_id: Optional[str])

Closes component and frees used resources.

Parameters: correlation_id – (optional) transaction id to trace execution through call chain.

configure(config: pip_services3_commons.config.ConfigParams.ConfigParams)

Configures component by passing configuration parameters.

Parameters: config – configuration parameters to be set.

create_endpoint()

fix_route(route) → str

is_open() → bool

Checks if the component is opened.

Returns: true if the component has been opened and false otherwise.

open(correlation_id: Optional[str])

Opens the component.

Parameters: correlation_id – (optional) transaction id to trace execution through call chain.

abstract register()

Registers all service routes in HTTP endpoint.

This method is called by the service and must be overriden in child classes.

register_interceptor(route: str, action: Callable)

Registers a middleware for a given route in HTTP endpoint.

Parameters

route – a command route. Base route will be added to this route
action – an action function that is called when middleware is invoked.

register_route(method: str, route: str, schema: Optional[pip_services3_commons.validate.Schema.Schema], handler: Callable)

Registers an action in this objects REST server (service) by the given method and route.

Parameters

method – the HTTP method of the route.
route – the route to register in this object’s REST server (service).
schema – the schema to use for parameter validation.
handler – the action to perform at the given route.

register_route_with_auth(method: str, route: str, schema: pip_services3_commons.validate.Schema.Schema, authorize: Callable, action: Callable)

Registers a route with authorization in HTTP endpoint.

Parameters

method – HTTP method: “get”, “head”, “post”, “put”, “delete”
route – a command route. Base route will be added to this route
schema – a validation schema to validate received parameters.
authorize – an authorization interceptor
action – an action function that is called when operation is invoked.

send_created_result(result: Any) → Optional[str]

Creates a callback function that sends newly created object as JSON. That callack function call be called directly or passed as a parameter to business logic components.

If object is not null it returns 201 status code. For null results it returns 204 status code. If error occur it sends ErrorDescription with approproate status code.

Parameters: result – a body object to result.
Returns: execution result.

send_deleted_result(result: Optional[Any] = None) → Optional[str]

Creates a callback function that sends newly created object as JSON. That callack function call be called directly or passed as a parameter to business logic components.

If object is not null it returns 200 status code. For null results it returns 204 status code. If error occur it sends ErrorDescription with approproate status code.

Parameters: result – a body object to result.
Returns: execution result.

send_error(error: Any) → str

Sends error serialized as ErrorDescription object and appropriate HTTP status code. If status code is not defined, it uses 500 status code.

Parameters: error – an error object to be sent.

send_result(result: Any) → Optional[str]

Creates a callback function that sends result as JSON object. That callack function call be called directly or passed as a parameter to business logic components.

If object is not null it returns 200 status code. For null results it returns 204 status code. If error occur it sends ErrorDescription with approproate status code.

Parameters: result – a body object to result.
Returns: execution result.

set_references(references: pip_services3_commons.refer.IReferences.IReferences)

Sets references to dependent components.

Parameters: references – references to locate the component dependencies.

unset_references(): Unsets (clears) previously set references to dependent components.