...
Response: Entity Body (on Success)
Returns a human-readable description of the service: in plain text, in an XML format, or both, TBA. See Questions or Issues, below.
Response: Entity Body (on Error)
Returns an XML document containing a description of the error. See Common System Specific Elements for details.
As RESTful Service - Ajax Patterns notes, "Error responses should ... be in human-friendly language and with examples and hyperlinks."
Questions or Issues
- We need to decide if this description is made available in plain text, in a particular XML format, or both. If both, the default format can be retrieved using the pattern above, and specific formats can be retrieved by adding filename extensions; e.g.:
- /{resources_as_a_plural_noun}/description.txt (for a plain text description)
- /{resources_as_a_plural_noun}/description.xml (for an XML-based description)
...
By default, the schema will be declared in the W3C XML Schema language.
Questions or Issues
...
Response: Entity Body (on Error)
Returns an XML document containing a description of the error. See Common System Specific Elements for details.
Questions or Issues
- If there may be a requirement to return schemas in additional schema languages, such as RELAX NG, the default format can be retrieved using the pattern above, and specific formats can be retrieved by adding filename extensions; e.g.
- /{resources_as_a_plural_noun}/schema.xsd (for a W3C XML Schema document)
- /{resources_as_a_plural_noun}/schema.rng (for a RELAX NG schema document)
...
| Note |
|---|
This section is an in-process placeholder. The notes below are very rough at present. |
Approaches to Search
As RESTful Service - Ajax Patterns notes:
... REST will always have different interpretations. The ambiguity is exacerbated by the fact that there aren't nearly enough HTTP methods to support common operations. The most common example is the lack of a search method, meaning that different people will design search in different ways.
The two most widely used approaches to REST-based search that we have observed to date involve a) submitting a request containing query parameters, via GET and b) constructing and submitting a structure, via POST. Some variations on these approaches, both observed and hypothesized, include:
...
| Note |
|---|
This section is an in-process placeholder. |
For some potential patterns, see "Handling arbitrary actions" in RESTful Service - Ajax Patterns.
Service Discovery
Description
...