liveBook · Manning

Contract

As explained in Designing AI Systems

An API is a defined interface through which software components communicate and invoke capabilities, including interfaces exposed by external systems.

An API contract defines how software components communicate: which operations are available, what data callers send, and what they can expect back. It gives service consumers a stable interface to capabilities without requiring them to manage the service’s internal complexity. section 3.1 section 2.0

For an AI platform, contracts connect several boundaries. An SDK contract governs how application developers compose platform capabilities and handle failures. An external API contract governs how clients access application workflows, including authentication and synchronous, asynchronous, or streaming interactions. Internal service contracts specify the operations and data exchanged between platform services. section 2.0 section 2.3 section 3.1

Design the contract around consumer needs, not just the transport. A frontend, mobile client, or external partner needs a usable way to invoke a workflow, while long-running AI operations may require different interaction patterns. Clear boundaries also let services scale and evolve independently. section 2.3 section 1.7

Session Service contract

A conversation workflow needs to create or resume sessions, list them, record and retrieve messages, and delete sessions. The service definition exposes five corresponding operations. GetOrCreateSession accepts a user ID and an optional session ID, so a caller can request either a fresh session or a previously identified one through the same operation. section 4.2

Listing 4.3 Protocol Buffer service definition for the Session Service
syntax = "proto3";
 
package sessions;
 
service SessionService {
    rpc GetOrCreateSession(GetOrCreateSessionRequest) 
        returns (GetOrCreateSessionResponse);
    rpc ListSessions(ListSessionsRequest)
        returns (ListSessionsResponse);
    rpc AddMessages(AddMessagesRequest) 
        returns (AddMessagesResponse);
    rpc GetMessages(GetMessagesRequest) 
        returns (GetMessagesResponse);
    rpc DeleteSession(DeleteSessionRequest) 
        returns (DeleteSessionResponse);
}
 

The Protocol Buffer service definition makes each Session Service operation and its request and response types explicit. section 4.2

The Model Service contract extends beyond generating a response: it supports model discovery, prompt management, custom model registration, and embedding generation. SDK methods, gateway routing, and other services depend on that shared specification. Provider adapters can then hide differences between model providers behind a unified interface. section 3.0 section 3.1

External APIs introduce another boundary: executing a tool can require authentication, failure handling, and waiting for a response. Wrapping those concerns lets application developers focus on the action rather than the connection. section 6.3

How Designing AI Systems covers it

How deep it goes
Specifies service operations and request and response structures, including optional session identifiers and message retrieval fields.
Examples
Illustrates contracts with patient intake workflows and Model and Session Service interfaces.
What you can do after
Evaluate service interfaces against consumer needs, available operations, data requirements, and AI interaction timing.
How it connects
Connects API contracts to SDKs, gRPC, API gateways, provider adapters, and service-oriented architecture.

Also explained in

Compare how 58 books explain contract →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Designing AI Systems. The section links point to the parts of the book it draws on.