Should a RESTful API have a schema?

Question

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 1

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.

Answer 2

You should document your RESTful API for those who use it. The schema is more specific to each data format that gets returned, which can be helpful. Here are example API references that define methods and response formats nicely:

The Google Maps Geocoding API (JSON and XML)

SoundCloud HTTP API Reference

CloudFlare API documentation v4

Twitter Search API

Mostly what I see are request methods documented with response examples shown and a chart explaining what to expect (not so often a formal schema on its own). Make it make sense to humans.