An application programming interface (API) defines how a caller requests functionality and understands the result. A library exposes types and functions; a service defines requests, responses, and endpoints. In either case, callers depend on the published contract, so a small, clear API is easier to use and to evolve without breaking their code. section 4.1 section 10.1
The contract takes different forms depending on what is calling:
- A logger library can export a constructor and methods while accepting an io.Writer for its output. Callers choose the destination without the logger needing to know its concrete type. section 4.1 section 4.2.2
- An HTTP endpoint pairs a method and path with a request and response shape. A guess submitted to PUT /games/{game_id} carries JSON such as {"guess":"hello"}; its handler decodes that body and rejects malformed input. section 8.2.3
- A gRPC service defines endpoints and messages in Protocol Buffers. Those definitions let clients know what to send and support generated clients, but the messages require their definitions to be read; ordinary curl is not enough to call the endpoint. section 10.1
- A Go program running as WebAssembly can expose a function to JavaScript. Registering it is not sufficient on its own: the Go program must remain running when the page calls it. section 12.2.2
Keep an external API outside the conversion logic
A currency converter needs exchange rates from an external bank API. Put the bank-specific call in a separate package, then let Convert accept a rate provider through a small local Go interface. Tests can supply a stub; replacing the provider later need not change the conversion logic. The Go interface is an internal contract for that dependency, not the bank API itself. section 6.5 section 6.5.5
Keep transport handling at the API boundary. A gRPC handler can turn an API request into domain values, call domain logic, then return API-specific values and status errors. This leaves business decisions, such as a default habit frequency, in the domain when they are business requirements rather than API rules. section 10.3.2
