Scope of a published interface.
WHAT TO ESTABLISH
Why you are publishing it.
WHAT GOOD REASONS LOOK LIKE
Customers automating their own work Partners building on you Integrations you will not build yourself
WHAT TO EXPOSE
What serves those purposes.
WHAT NOT TO EXPOSE
Your internal model, directly.
WHY
It ties you to your current structure permanently.
WHAT TO DESIGN INSTEAD
An interface expressing what callers need, independent of how you store it.
WHAT TO START WITH
Read access to the main resources.
WHY READ FIRST
It is lower risk, and it covers most early demand.
WHAT TO ADD NEXT
Writes for the operations callers actually ask for.
HOW TO KNOW
Ask them, and watch what they attempt.
WHAT TO WITHHOLD DELIBERATELY
Administrative operations Anything bypassing business rules Anything you are not prepared to support indefinitely
WHY THAT LAST POINT
Publishing is a commitment, and withdrawal is painful.
WHAT TO STATE CLEARLY
What is stable, and what is experimental.
WHAT TO PROVIDE FOR EXPERIMENTAL PARTS
A clear marker, and an expectation that they may change.
WHAT TO NEVER DO
Publish something you intend to remove shortly.
