service

A service defines an interface or API.

A service can be used to describe a programming language interface, REST API, Open API, Serverless functions etc. As a modeller, you purely focus on the API abstractions, not implementation details.

In addition to describing what methods are available on the API, an ALFA service declaration also captures how to create or instantiate the service. In the declaration below, the OrderService can be created by passing in an authToken attribute.

service OrderService( authToken : uuid ) {
    placeOrder( ord : Order ) : try< ConfirmedOrder >
    getOrder( Id : uuid ) : Order
    getOrders() : list< Order >
}

service UserMetrics {
    loginEvents() : stream< LoginEvent >
    purge( category : string ) : future< EventCompletion >
}

Error and Exceptions

These can be modelled using:

• either< Result, Error > - useful for capturing a result or custom error details.

• try<Result> - useful for capturing a result or error message.

• Using raises ( Exception1, Exception2 ) at the end of the declaration

  ALFA record types can be used in raises list of exceptions. Such records need to be annotated with @alfa.lang.Exception to denote they are exception types.

Parameter Scope

Some target languages/platform ( C++ / OMG IDL ) pay attention to parameter scope and how they are passed.

To support this usecase, ALFA optionally supports specifiying in, out and inout as the scope for a service parameter.

service ProductService() {
    locateProducts( in Division : string, out Products : list< Product > ) : void
}