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

They are optional. If you need fine-grained filtering of user requests with consideration on both the syntax and semantics on the contents, you use it.

1. Here's an RFC guideline mentions about XML schema.

https://tools.ietf.org/html/rfc3470

"XML Schema (defined in [41] and [42]) provides additional features to allow a tighter and more precise specification of allowable protocol syntax and data type specifications."

2. Here's IETF draft for JSON schema: https://tools.ietf.org/html/draft-zyp-json-schema-04

"JSON Schema provides a contract for what JSON data is required for a given application and how to interact with it. JSON Schema is intended to define validation, documentation, hyperlink navigation, and interaction control of JSON data."

As you can see, IETF did not accept this as an RFC (it is still a draft). They thought this is too much for simple protocol like JSON. However many open source projects rely on this draft.

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.

Answer 3

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.