Software Engineering & Object-Oriented Analysis & Design — Software Process and Requirements, NEC licence examination syllabus (Nepal Engineering Council).
Interface Specification
Systems fail at their boundaries, so the boundaries get specified first.
🌍 Where this lives: almost no software runs alone. A licence-issuing system talks to a national ID service, a payment gateway, an SMS provider and a printer. Each of those is a boundary you do not control, and every one of them will change without asking you. Interface specification is the discipline of writing down exactly what crosses each boundary so that when the other side changes, you can prove whose fault it is — and so your own module can be built and tested before the other side even exists. Search "interface contract consumer driven contract testing".
Why interfaces get their own specification
A new system almost never replaces everything. It must operate
alongside existing systems, so the requirements document must
define the interfaces to those systems PRECISELY — and early,
because:
· SUBSYSTEMS CAN BE DEVELOPED IN PARALLEL only once the
interface between them is fixed. Until then, two teams
cannot work independently.
· The interface is where INTEGRATION FAILURES happen.
Individually correct modules that disagree about their
boundary produce the bugs that surface latest and cost most.
· The interface is a CONTRACT. If a supplier delivers a
subsystem, the interface specification is the acceptance
criterion.
· A specified interface can be STUBBED, so your side is
testable before the other side is delivered.
THREE KINDS OF INTERFACE (Sommerville):
1. PROCEDURAL INTERFACES
One subsystem offers a set of services (an API) that others
call. Also called an APPLICATION PROGRAMMING INTERFACE.
Specified by: operation names, parameter types, return
types, exceptions, pre/postconditions.
interface PrintServer {
// requires: printer exists and doc is not empty
// ensures: doc placed on printer's queue
void print(Printer p, PrintDoc doc)
throws UnknownPrinter, PrinterBusy;
void displayPrintQueue(Printer p);
void cancelPrintJob(Printer p, PrintDoc doc);
}
THE EXCEPTIONS ARE PART OF THE INTERFACE. An operation that
documents its parameters but not its failure modes is
half-specified, and the caller will handle failure wrongly.
2. DATA STRUCTURES / DATA INTERFACES
Data passed from one subsystem to another. Specified by
field names, types, units, ranges, optionality, ordering
and encoding.
record LicenceApplication {
applicationNo : CHAR(12) // '' never valid
applicantName : VARCHAR(120) // UTF-8
appliedOn : DATE // ISO-8601, Nepal time
feePaid : NUMERIC(10,2) // NPR, 2 dp, ≥ 0
status : ENUM{RECEIVED, UNDER_REVIEW,
APPROVED, REJECTED, ISSUED}
officerId : CHAR(8) OPTIONAL // null until reviewed
}
UNITS AND TIME ZONE ARE PART OF THE SPECIFICATION. The
Mars Climate Orbiter was destroyed in 1999 because one
interface used pound-force-seconds and the other newton-
seconds; both modules were internally correct. Currency and
timestamps cause the same class of failure in business
systems every day.
3. DATA REPRESENTATIONS / DATA-EXCHANGE INTERFACES
The wire format and its ordering: XML schema, JSON schema,
fixed-width record layout, byte order, character encoding,
protocol.
Two systems can agree on the data structure and still fail
on representation — big-endian vs little-endian, CRLF vs
LF, UTF-8 vs Latin-1, '2026-01-05' vs '05/01/2026'.
SPECIFICATION NOTATIONS:
informal prose + tables (readable, ambiguous)
structured an interface definition language — IDL, OpenAPI,
Protocol Buffers, WSDL, Java/C++ interfaces
formal Z, VDM, algebraic specification (provable,
unreadable to customers)
The structured middle is where real projects live: OpenAPI or
a .proto file is precise AND machine-processable — it generates
client code, server stubs, documentation and validation from
ONE definition, which removes the possibility of the two sides
drifting apart.
A specified interface, in full
OPERATION POST /api/licences/{applicationNo}/status
PURPOSE Records a status transition for an application.
INPUTS path applicationNo : CHAR(12), digits only
body newStatus : ENUM (see LicenceApplication)
officerId : CHAR(8)
remarks : VARCHAR(500), OPTIONAL
header Authorization : Bearer <JWT>
OUTPUTS 200 { applicationNo, status, changedOn, officerId }
400 malformed body / unknown status value
401 missing or expired token
403 officer not authorised for this transition
404 applicationNo not found
409 transition not permitted from current status
422 remarks required for REJECTED but absent
PRECONDITION the application exists;
(currentStatus, newStatus) is a legal transition;
the officer holds the required role
POSTCONDITION status is newStatus;
one audit row exists recording old → new, the
officer and the timestamp;
no other application is modified
LEGAL TRANSITIONS — the state machine IS part of the interface:
RECEIVED → UNDER_REVIEW
UNDER_REVIEW → APPROVED | REJECTED
APPROVED → ISSUED
REJECTED → (terminal)
ISSUED → (terminal)
IDEMPOTENCY Re-posting the same transition that already
applied returns 200 with the unchanged record,
NOT 409. This matters because clients retry on
network timeouts, and a retry must not be an
error.
RATE LIMIT 60 requests/minute per officer; 429 beyond.
VERSIONING Breaking changes ship under /api/v2/. A new
OPTIONAL field is not breaking; a new required
field, a removed field or a narrowed type is.
WHAT THIS SPECIFICATION MADE POSSIBLE:
· the client team can build and test against a stub today
· the 409 case forced someone to write down the state machine
— which nobody had done
· the idempotency rule prevented a real production bug class
· the versioning rule tells both sides what they may change
without a meeting
The state machine in the example above is the important lesson. Writing down the 409 case forced someone to enumerate the legal transitions — which nobody had done, and which is genuinely a requirement. Specifying an interface reliably discovers requirements, because you cannot list the errors without knowing the rules.
🌍 Go further: the modern practice is contract testing — the consumer writes down what it expects from the interface, and that expectation runs as an automated test against the provider in CI. If the provider changes something breaking, the provider's own pipeline fails, before deployment, naming the consumer that will break. It turns the interface specification from a document people forget into a test that cannot be ignored, and it works even when the two sides are owned by different teams or companies. Search "Pact consumer driven contract testing".
💡 Exam angle: name and explain the three kinds of interface — procedural, data structure, data representation — with an example of each, and state why interfaces are specified early (parallel development, integration failures, contractual acceptance, stubbing). Be ready to write a procedural interface specification in a Java-like syntax with operations, parameters and exceptions. Mention the three notation levels (informal, structured, formal) and that units and encodings are part of the specification — the Mars Climate Orbiter is the standard example.
Syllabus points
Specifying interfaces
Create a free account to tick topics off, take notes as you read, watch the video lessons and get a day-by-day study plan built around your exam date.
Related topics in Software Process and Requirements