RestService

Implements: IRegisterable

Description

The RestService class allows you to create REST services that receive remote calls via the 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) 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: SSL private key in PEM
  • ssl_crt_file: SSL certificate in PEM
  • ssl_ca_file: 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
• *:traces:*:*:1.0 - (optional) ITracer components to record traces
• *:discovery:*:*:1.0 - (optional) IDiscovery services to resolve connection
• *:endpoint:http:*:1.0 - (optional) HttpEndpoint reference

Constructors

InheritRestService

InheritRestService is create new instance of RestService

InheritRestService(overrides IRestServiceOverrides) *RestService

• overrides: IRestServiceOverrides - ingerited rest service

Fields

Methods

Close

Closes a component and frees used resources.

(c *RestService) Close(ctx context.Context, correlationId string) error

• ctx: context.Context - operation context.
• correlationId: string - (optional) transaction id used to trace execution through the call chain.
• returns: error - returns error if not closed.

Configure

Configures a component by passing its configuration parameters.

(c *RestService) Configure(ctx context.Context, config *cconf.ConfigParams)

• ctx: context.Context - operation context.
• config: *cconf.ConfigParams - configuration parameters, containing a “connection(s)” section.

Instrument

Adds instrumentation to log calls and measure call time. It returns a Timing object that is used to end the time measurement.

(c *RestService) Instrument(ctx context.Context, correlationId string, name string) *InstrumentTiming

• correlationId: string - (optional) transaction id used to trace execution through the call chain.
• name: string - method name.
• returns: *InstrumentTiming - instrument Timing object to end the time measurement.

GetCorrelationId

GetCorrelationId method returns CorrelationId from request

(c *RestService) GetCorrelationId(req *http.Request) string

• req: *http.Request - an HTTP request
• returns: string - correlation_id or empty string

IsOpen

Checks if the component is open.

(c *RestService) IsOpen() bool

• returns: bool - True if the component has been opened and False otherwise.

Open

Opens the component.

(c *RestService) Open(ctx context.Context, correlationId string) error

• ctx: context.Context - operation context.
• correlationId: string - (optional) transaction id used to trace execution through the call chain.
• returns: error - error or nil no errors occured.

RegisterInterceptor

Registers a middleware for a given route in HTTP endpoint.

(c *RestService) RegisterInterceptor(route string, action func(res http.ResponseWriter, req *http.Request, next http.HandlerFunc))

• route: string - command route. Base route will be added to this route
• action: func(res http.ResponseWriter, req *http.Request, next http.HandlerFunc) - action function that is called when middleware is invoked.

RegisterOpenApiSpec

Registers the open api spec.

(c *RestService) RegisterOpenApiSpec(content string)

• content: string - response header content

RegisterOpenApiSpecFromFile

Registers the open api spec from a file.

(c *RestService) RegisterOpenApiSpecFromFile(path string)

• path: string - path to the file

RegisterRoute

Registers a route in HTTP endpoint.

(c *RestService) RegisterRoute(method string, route string, schema *cvalid.Schema, action func(res http.ResponseWriter, req *http.Request))

• method: string - HTTP method: “get”, “head”, “post”, “put”, “delete”
• route: string - command route. The base route will be added to this route
• schema: *cvalid.Schema - validation schema to validate received parameters.
• action: func(res http.ResponseWriter, req *http.Request) - action function that is called when an operation is invoked.

RegisterRouteWithAuth

Registers a route with authorization in HTTP endpoint.

(c *RestService) RegisterRouteWithAuth(method string, route string, schema *cvalid.Schema, authorize func(res http.ResponseWriter, req *http.Request, next http.HandlerFunc), action func(res http.ResponseWriter, req *http.Request))

• method: string - HTTP method: “get”, “head”, “post”, “put”, “delete”
• route: string - command route. The base route will be added to this route
• schema: *cvalid.Schema - validation schema to validate received parameters.
• authorize: func(res http.ResponseWriter, req *http.Request, next http.HandlerFunc) - authorization interceptor
• action: func(res http.ResponseWriter, req *http.Request) - action function that is called when an operation is invoked.

Register

Register method are registers all service routes in HTTP endpoint.

(c *RestService) Register()

SendCreatedResult

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

If the object is not nil, it returns 200 status code. For nil results it returns 204 status code. If an error occurs, it sends ErrorDescription with the approproate status code.

(c *RestService) SendCreatedResult(res http.ResponseWriter, req *http.Request, result interface{}, err error)

• res: http.ResponseWriter - an HTTP request
• req: *http.Request - an HTTP response
• result: interface{} - an execution result
• error: error - (optional) error objrct to send

SendDeletedResult

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

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

(c *RestService) SendDeletedResult(res http.ResponseWriter, req *http.Request, result interface{}, err error)

• res: http.ResponseWriter - an HTTP request
• req: *http.Request - an HTTP response
• result: interface{} - body object to result
• error: error - (optional) error objrct to send.

SendError

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

(c *RestService) SendError(res http.ResponseWriter, req *http.Request, err error)

• res: http.ResponseWriter - an HTTP request
• req: *http.Request - an HTTP response
• error: error - error object to be sent.

SendResult

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

If the object is not nil it returns 200 status code. For nil results, it returns 204 status code. If an error occurs, it sends ErrorDescription with the approproate status code.

(c *RestService) SendResult(res http.ResponseWriter, req *http.Request, result interface{}, err error)

• res: http.ResponseWriter - an HTTP request
• req: *http.Request - an HTTP response
• result: interface{} - body object to result
• error: error - error object to be sent.

SetReferences

Sets references to dependent components.

(c *RestService) SetReferences(ctx context.Context, references crefer.IReferences)

• ctx: context.Context - operation context.
• references: crefer.IReferences - references to locate the component dependencies.

UnsetReferences

Unsets (clears) previously set references to dependent components.

(c *RestService) UnsetReferences()

Examples

type MyRestService struct {
	*RestService
	controller IMyController
}
...
func NewMyRestService() *MyRestService {
	c := MyRestService{}
	c.RestService = services.NewRestService()
	c.RestService.IRegisterable = &c
	c.numberOfCalls = 0
	c.DependencyResolver.Put(context.Background(), "controller", crefer.NewDescriptor("mygroup", "controller", "*", "*", "1.0"))
	return &c
}

func (c * MyRestService) SetReferences(ctx context.Context, references IReferences) {
	c.RestService.SetReferences(ctx, references);
	resolv := c.DependencyResolver.GetRequired("controller");
	if resolv != nil {
		c.controller, _ = resolv.(IMyController)
	}
}

func (c *MyRestService) getOneById(res http.ResponseWriter, req *http.Request) {
	params := req.URL.Query()
	vars := mux.Vars(req)

	mydataId := params.Get("mydata_id")
	if mydataId == "" {
		mydataId = vars["mydatay_id"]
	}
	result, err := c.controller.GetOneById(params.Get("correlation_id"), mydataId),
	c.SendResult(res, req, result, err)
}

func (c * MyRestService) Register() {
	c.RegisterRoute(
		"get", "get_mydata/{mydata_id}",
		&cvalid.NewObjectSchema().
			WithRequiredProperty("mydata_id", cconv.String).Schema,
		c.getOneById,
	)
	...
}


service := NewMyRestService();
service.Configure(context.Background(), cconf.NewConfigParamsFromTuples(
	"connection.protocol", "http",
	"connection.host", "localhost",
	"connection.port", 8080,
));
service.SetReferences(context.Background(), cref.NewReferencesFromTuples(
	cref.NewDescriptor("mygroup","controller","default","default","1.0"), controller
));

opnRes := service.Open(context.Background(), "123")
if opnErr == nil {
	fmt.Println("The REST service is running on port 8080");
}

See also

• RestClient