We like to think of REST as a standard, but it's a very flexible standard that's open to a lot of interpretation. In order to help keep development teams focused and make it easier for the QA team to know what to expect, I have created (with a lot of collaboration!) some basic guidelines for how I like to design API contracts.
The goal of the API Contract is to provide a consistent experience to the consumer of the API. The basic rule being "don't make me think!"
The assumption is that if one method works on one resource or collection, the same rules should apply in another location. For example, you wouldn't expect that one item is returned in XML and another is in JSON. You would expect that if you use size=x on one collection that you wouldn't use offset=x on another.
Honestly there is no right-or-wrong when it comes to an agreed upon contract, but you have to agree on that contract first. Once you have a basic set of expectations, you can revisit the agreement and see f you need to make exceptions or even expand the agreement to accommodate new requirements.
The Services MandateWe subscribe to a modified version of the 2002 Bezos Mandate that took Amazon from a heavily manual data shop to the behemoth that it is today:
- All teams will henceforth expose their data and functionality through service interfaces.
- Teams must communicate with each other through these interfaces.
- There will be no other form of interprocess communication allowed: no direct linking, no direct reads of another team's data store, no shared-memory model, no back-doors whatsoever. The only communication allowed is via service interface calls over the network.
- All services should be exposed as RESTful APIs over https
- All service interfaces, without exception, must be designed from the ground up to be externalizable. That is to say, the team must plan and design to be able to expose the interface to developers in the outside world. No exceptions.
- Thank you; have a nice day!