Design Model API For Clients

Assumptions and Terminology

Let foo be a service within the system. In what follows, we discuss the design of a client-side API for foo. In the process, we outline a generic model for similar APIs based on a small number of classes and interfaces. These compilation units are placed in org.gcube.common.clients.api package and are implemented in a common-clients-api library.

We work under the following assumptions and using the following terminology:

• services: foo is an HTTP service, in that it uses HTTP at least as its transport protocol. At the time of writing, all system services are more specifically WS RPC services, i.e. use SOAP over HTTP to invoke service-specific APIs. Some such services are stateless, in that their endpoints do not manage any form of state on behalf of clients. Other services are instead stateful, in that their endpoints host a number of service instances, all of which maintain state for a class of clients1. In the future, system services may also be REST services, in the broad sense of stateless services that use HTTP as their application protocol2.
• deployments: foo may be (statically or dynamically) deployed at multiple network addresses. We refer to a service deployment at any given address as a service replica3. Discovery Services are available within the system to locate service endpoints that are deployed at different addresses.
• scoped requests: foo may operate in multiple scopes, where each scope partitions the local resources that are visible to its clients, as well as the remote resources that are visible to the

operations that foo carries out on behalf of its clients. In particular, the operations of foo may result in the creation of state in a given scope, either locally to foo or remotely, by interaction with other services that create state on behalf of foo and/or its clients. Service scoping requires that requests to foo are scoped, marked with the scope within which they are intended to occur. Unscoped requests or requests made outside one of foo’s scopes are rejected by it.

• secure requests : foo may perform a range of authentication and authorisation checks, including scope checks, in order to restrict access to its operations to distinguished clients. Service security requires that requests made to foo be marked with adequate credentials. Unsecure requests or secure requests that fail authorisation checks are rejected by foo.
• clients: a client of foo may be internal to the system (i.e. a system component in turn) or external to it. Clients often operate within a dedicated runtime, and in this case we refer to them as pure clients. In other cases, they share a common runtime and, like foo, they may be managed by some container. In particular, clients may be services in turn, and in this case we refer to them as a client services.