Interface definition

Copyright 2017 Graham Berrisford. One of about 300 papers at Last updated 29/06/2017 19:13


An interface in general

An interface is a list of services (aka operations or methods) that is required or provided by a system of any kind.

An interface may be coupled to one system that provides every service in it.

Or else decoupled, and presented as a façade to several systems.


Each service/operation can be defined in service contract that captures functional and non-functional requirements

·          Signature (name, inputs, outputs)

·          Functional rules (preconditions and post conditions)

·          Non-functional attributes (response time, throughput, availability, security etc.)


If the non-functional attributes (e.g. response time and security) of all services are the same, they can be treated as attributes of the whole interface instead.


User interface design

A user interface is façade via which enables the user to invoke services/operations (which may each be defined as above).

But given a Human-Computer Interface (HCI) that is only a small part of what UI design is about.

UI design is very extensive topic, for which there are User Experience (UEx) training courses.


Application use case

An application use case is a process during which a user makes use of a system, via an HCI.

Each use case can be defined by defining a service contract for the whole use case, and adding process flow.

·          Service contract

o   Signature (name, inputs, outputs)

o   Functional rules (preconditions and post conditions)

o   Non-functional attributes (response time, throughput, availability, security etc.)

·          Process flow

o   Main path (numbered steps)

o   Exception paths (cross-referenced to main path steps).


A use case may be equate to an “epic” in the SCRUM agile development method,

Each step in the flow of a use case might be defined as a “user story”.


Application Programming Interface (API)

Programmers define an API using an interface definition language like WSDL.

An API includes what a programmer needs to know to call services/operations.

For each, that is likely to include.

·         Service signature (name, inputs, outputs, fault messages)

·         One or more protocols for invoking the operation (e.g. SOAP, HTTP)

·         One or more addresses at which to find the operation (URLs)


To code and test a service/operation, the programmer needs additional information.

·          Functional rules (preconditions and post conditions)

·          Non-functional attributes (response time, throughput, availability, security etc.)


API policies

Programmers can attach policies to APIs.

I don’t understand policies, but I know policies can relate to non-functional requirements.

And by default, a policy applies to the entire API.


References for policies

A policy is a mechanism for enforcing filters on traffic.

By default, a policy applies to the entire API, filtering traffic requests to every resource and method [operation or service].

Filters generally control authentication, access, allotted consumption, and service level access (SLA).

An API Manager provides a number of policies; you can also build custom policies.

By exposing an API through Apigee Edge, you gain the ability to modify and monitor its behavior using out-of-the-box policies.

Edge's out-of-the-box policies enable you to augment your API with sophisticated features to control traffic, enhance performance, enforce security,

and increase the utility of your APIs, without requiring you to write any code or to modify any backend services.

Extension policies enable you to implement custom logic in the form of JavaScript, Python, Java, and XSLT.


Apigee provides the following categories of policies.

Traffic management policies

Mediation policies

Security policies

Extension policies

Traffic management policies let you configure cache, control traffic quotas and spikes, set concurrent rate limits, and so on.

Cache policies

Concurrent Rate Limit policy

Quota policy

Reset Quota policy

Spike Arrest policy

Mediation policies let you perform message transformation, parsing, and validation, as well as raise faults and alerts.

Access Entity policy

Assign Message policy

Extract Variables policy

JSON to XML policy

Key Value Map Operations policy

Raise Fault policy

SOAP Message Validation policy

XML to JSON policy

XSL Transform policy

Security policies let you control access to your APIs with OAuth, API key validation, and other threat protection features.

Access Control policy

Basic Authentication policy

JSON Threat Protection policy

LDAP policy *†

OAuth v2.0 policies

OAuth v1.0a policy

Regular Expression Protection policy

SAML Assertion policies

Verify API Key policy

XML Threat Protection policy

Extension policies let you provide custom policy functionality, with support for such features as service callout, message data collection, and calling Java, JavaScript, and Python behavior you have created.

Flow Callout policy

Java Callout policy *

JavaScript policy

Message Logging policy

Python Script policy *

Service Callout policy

Statistics Collector policy



All free-to-read materials at are paid for out of income from Avancier’s training courses and methods licences.

If you find the web site helpful, please spread the word and link to in whichever social media you use.