Defining Endpoint Contracts

######The intended use of an endpoint contract is to identify a set of remote services and provide information for successful communication.
You start off by defining and exact copy (mirror) of the endpoint, with all its public methods (services), on a single interface. This interface is then annotated to provide information (metadata) on how to reach the endpoint services and communicate with them using data structures & a common format which both ends understand.

Almost all usage of the ZombieLink API revolves around this set of annotations for populating endpoint metadata.

####1. Identifying Endpoints

• The @Endpoint annotation is used to mark interfaces which specify contracts for remote endpoints.
• It takes a mandatory host parameter which specifies the target endpoint host-name for all service invocations.

@Endpoint("www.google.com")
public interface CurrencyConverterEndpoint {}

• It can be optionally configured to use a different scheme and port, along with a root-path.

@Endpoint(scheme = "https", value = "www.google.com", port = "443", path = "/ig/calculator")
public interface CurrencyConverterEndpoint {}

####2. Defining Services

• Each endpoint service can be identified using the @Request annotation.

@Request
public abstract String timestamp();

By default each service is executed as an HTTP GET request on the endpoint root-path with no request parameters.

• To populate request parameters, define them as arguments to the service method and annotate them with @Param.

@Request
public abstract String convert(@Param(name = "q") String conversionString);

• A request may also be configured to use an alternative HTTP method type or be invoked on a sub-path from the root.

@Request(path = "/ig/calculator", method = RequestMethod.HTTP_POST)
public abstract String convert(@Param(name = "q") String conversionString);

• At times, certain request parameters remain constant for a particular invocation context. For example administrative credentials, language, number of results ..etc. These static request parameters can be defined using @Request.Param on the params attribute.

@Request(path = "/ig/calculator", params = {@Request.Param(name = "hl", value = "en")})
public abstract String convert(@Param(name = "q") String conversionString);

For request parameters which are populated rarely, use an @Param annotation with a defaultValue attribute to fallback to if null is received.

####3. Populating Headers Certain requests require special HTTP headers to be set for proper processing at the remote end. These could be Content-Type, User-Agent, Authorization ...etc.

• Static headers are defined at the request level using the @HeaderSet annotation which takes a set of @HeaderSet.Header annotations.

@Request
@HeaderSet({@HeaderSet.Header(name = "Accept", value = "application/rss+xml"),
            @HeaderSet.Header(name = "Accept-Charset", value = "utf-8")})
public abstract String getRSSFeed();

• Dynamic headers are populated via service arguments annotated with @Header.

@Request
public abstract String crawlBlog((@Header("User-Agent") String userAgent)