Should a RESTful API have a schema?
I was told recently that a proper RESTful API should define a schema for the resources representations it accepts and returns. For example XSD for XML and JSON Schema for JSON.
However in all the books and articles on REST I went through this has never seem not only prominent, but even mentioned.
Could someone provide some authoritative resources, to clarify if we should be providing schema when developing RESTful APIs?
Answer
You have to define and communicate the request and response interfaces to your RESTful API somehow so that callers know what you expect in the request and what they can expect in a response.
RESTful API: Schema vs Other Interface Definition
Whether you use a schema (XSD, JSON Schema, etc), or some other form (natural language, examples, etc), or some combination to define your interfaces is up to you to decide. Here are some factors to inform your decision:
How well-known of a convention you'll use.
Schema: XSD is a W3C standard used across many industries; JSON Schema is the well-known alternative to XSD for JSON.
Other: Natural language and examples are viable and very helpful, although often ambiguous or incomplete.
Which convention your community will most appreciate.
Schema: XSD especially tends to be appreciated more by communities who have already invested in developing standard XSDs for their industry.
Other: Natural language and examples tend to be appreciated by newcomers.
How automatable of a validation process you'll use.
Schema: Both XSD and JSON Schema offer off-the-shelf, automated validation.
Other: Natural language and examples require ad hoc effort for validation.
How tightly or loosely typed of an interface you'll use.
Schema: XSD and JSON can express a range of type specificity but shine when detailed type specificity is desired.
Other: Natural language and examples can convey type requirements albeit often imprecisely.
Additional RESTful API Considerations
Finally, note that you'll have further decisions to make beyond schema vs non-schema:
- How you'll version the interfaces over time.
- What HTTP URL structure, methods, responses codes, etc you'll use.
- Whether to manage all of these considerations in using Swagger, RAML, Apiary, Apigee, or other API framework.
These all are important parts of the communication of your REST API to callers of your service in addition to the schema vs other interface definition decision.