...
Purpose
Retrieves a human-readable description of the service. This also verifies that the service exists, without interacting with the resources that it provides.
Request
| Code Block |
|---|
GET /{resources_as_a_plural_noun}/description
|
...
- Sent by a client in the body of a request, to perform a Create operation.
- Sent by a client in the body of a request, to perform an Update operation.
- Returned by the service in a response, when a specific object (entity) is requested.
- Returned by the service in a response, when a list of objects (entities) is requested, in a format that returns full object records, (rather than just hyperlinks, or just hyperlinks accompanied by abbreviated object records).
Request
| Code Block |
|---|
GET /{resources_as_a_plural_noun}/schema
|
There will be only one schema returned per resource. If there may be typed resources, or child resources, available anywhere within the URL path, schemas for these resources can be retrieved via variations on this generic pattern, as in this example:
| Code Block |
|---|
GET /{resources_as_a_plural_noun}/{typed_or_child_resources_as_a_plural_noun}/schema
|
...
Purpose
Creates a new resource of the specified type.
Request
| Code Block |
|---|
POST /{resources_as_a_plural_noun}
|
...
If there may be typed resources, or child resources, available anywhere within the URL path, new resources of that type can be created via variations on this generic pattern, as in this example:
| Code Block |
|---|
POST /{resources_as_a_plural_noun}/{typed_or_child_resources_as_a_plural_noun}
|
...
Purpose
Reads (aka retrieves or returns) a representation of a specific instance of this resource.
Request
| Code Block |
|---|
GET /{resources_as_a_plural_noun}/{resource_identifier}
|
...
If there may be typed resources, or child resources, available anywhere within the URL path, these resources can be retrieved via variations on this generic pattern, as in this example:
| Code Block |
|---|
GET /{resources_as_a_plural_noun}/{typed_or_child_resources_as_a_plural_noun}/{resource_identifier}
|
...
The default behavior is to return hyperlinks, each accompanied by the minimum information required to identify, in a human-readable format, their linked-to resources.
Request
| Code Block |
|---|
GET /{resources_as_a_plural_noun}
|
| Code Block |
|---|
GET /{resources_as_a_plural_noun}?{optional_query_parameters ...}
|
If there may be typed resources, or child resources, available anywhere within the URL path, these resources can be retrieved via variations on this generic pattern, as in these examples:
| Code Block |
|---|
GET /{resources_as_a_plural_noun}/{typed_or_child_resources_as_a_plural_noun}
|
| Code Block |
|---|
GET /{resources_as_a_plural_noun}/{typed_or_child_resources_as_a_plural_noun}?{optional_query_parameters ...}
|
A highly recommended child resource, for read (multiple) operations, will return a count of the numbers of records to be returned, as in this example:
| Code Block |
|---|
GET /{resources_as_a_plural_noun}/count
|
| Code Block |
|---|
GET /{resources_as_a_plural_noun}/count?{optional_query_parameters ...}
|
...
Code | Meaning | Returned When |
|---|---|---|
200 | OK | A list of the resources was returned successfully. |
400 | Bad Request | There was an error in the query parameters submitted with the request. |
403 | Forbidden | A list of resources could not be returned because the client submitting the request was not authorized to read that list. |
404 | Not Found | The resource at /{resources_as_a_plural_noun} does not exist. |
500 | Internal Server Error | A service error prevented the list of resources from being read. |
...
Purpose
Completely updates in place (i.e. replaces) an existing resource of the specified type.
Request
| Code Block |
|---|
PUT /{resources_as_a_plural_noun}/{resource_identifier}
|
...
If there may be typed resources, or child resources, available anywhere within the URL path, resources of that type can be updated via variations on this generic pattern, as in this example:
| Code Block |
|---|
PUT /{resources_as_a_plural_noun}/{typed_or_child_resources_as_a_plural_noun}/{resource_identifier}
|
...
Purpose
Deletes a specific instance of this resource.
Request
| Code Block |
|---|
DELETE /{resources_as_a_plural_noun}/{resource_identifier}
|
...
If there may be typed resources, or child resources, available anywhere within the URL path, resources of that type can be deleted via variations on this generic pattern, as in this example:
| Code Block |
|---|
DELETE /{resources_as_a_plural_noun}/{typed_or_child_resources_as_a_plural_noun}/{resource_identifier}
|
...
... there is rough consensus among search engines on what a query should look like: quotes mark "phrase searches", you use "+" to say a word must +occur and "-" to -exclude words. You URI-restrict searches like so: tbray.org:kirkby. Down the road, you might want to support something like XPath or even XQuery, but that would work fine through a Web interface too.
So a search engine would publicize a URI that you could use HTTP GET on to run searches; arguments would be q for the query, mr for maximum results, and ie for input-encoding. So a complete search request might look like:
| Code Block |
|---|
q=%2busername:miso%20%2bhostname:miso.demo.sun.com%20%2bsubject:test
|
...
Leonard Richardson and Sam Ruby, RESTful Web Services (via Safari Online if you have access)
Michael Mahemoff, et al., RESTful Service - Ajax Patterns
...
Aaron Johnson, Clearspace and Meaningful URLs
RedRata blog on REST-ful URI Design talks about different patterns, plurals and not plurals, sub-resources, etc.