From c4536a54c0d7185471f4eb5bf7ead6839aed7d17 Mon Sep 17 00:00:00 2001 From: Todd Fredrich Date: Fri, 18 May 2012 13:08:18 -0600 Subject: [PATCH] Updated meta description for resources.html and restquicktips.html since they were duplicates. --- resources.html | 2 +- restquicktips.html | 8 +++----- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/resources.html b/resources.html index d1eb23d..74b7334 100644 --- a/resources.html +++ b/resources.html @@ -4,7 +4,7 @@ RESTful Web Services Resources - + diff --git a/restquicktips.html b/restquicktips.html index 4575359..28e76d7 100644 --- a/restquicktips.html +++ b/restquicktips.html @@ -4,7 +4,7 @@ HTTP Methods for RESTful Services - + @@ -39,16 +39,14 @@

REST API Quick Tips

Whether it's technically RESTful or not (according to the six constraints mentioned above), here are a few recommended REST-like concepts that will result in better, more usable services:

-

Not SOAP

-

There are legitimate reasons to have a SOAP API, and translating a massive API from a legacy SOAP to REST interface is quite difficult, but it’s incredibly difficult to consume SOAP if you have to develop a client library from scratch, access it via a Web UI, or do anything non-standard.

Use HTTP Verbs to Mean Something

Any API consumer is capable of sending GET, POST, PUT, and DELETE verbs, and they greatly enhance the clarity of what a given request does. Also, GET requests must not change any underlying resource data. Measurements and tracking may still occur, which updates data, but not resource data identified by the URI.

Sensible Resource Names

-

Having sensible resource names or paths (e.g., /posts/23 instead of /api?type=posts&id=23) improves the clarity of what a given request does. Using URL query-string parameters is fantastic for filtering, but not for resource names.

+

Having sensible resource names or paths (e.g., /posts/23 instead of /api?type=posts&id=23) improves the clarity of what a given request does. Using URL query-string parameters is fantastic for filtering, but not for resource names.

Appropriate resource names provide context for a service request, increasing understandability of the service API. Resources are viewed hierarchically via their URI names, offering consumers a friendly, easily-understood hierarchy of resources to leverage in their applications.

Resource names should be nouns—avoid verbs as resource names. It makes things more clear. Use the HTTP methods to specify the verb portion of the request.

XML and JSON

-

Unless the costs of offering both JSON and XML are staggering, offer them both. Ideally, let consumers switch between them by just changing an extension from .xml to .json. In addition, for supporting AJAX-style user interfaces, a wrapped response is very helpful. Provide a wrapped response, either by default or for separate extensions, such as .wjson and .wxml to indicate the client is requesting a wrapped JSON or XML response. (see Wrapped Responses below).

+

Favor JSON support, but unless the costs of offering both JSON and XML are staggering, offer them both. Ideally, let consumers switch between them by just changing an extension from .xml to .json. In addition, for supporting AJAX-style user interfaces, a wrapped response is very helpful. Provide a wrapped response, either by default or for separate extensions, such as .wjson and .wxml to indicate the client is requesting a wrapped JSON or XML response.

JSON in regards to a "standard" has very few requirements. And those requirements are only syntactical in nature, not about content format or layout. In other words, the JSON response to a REST service call is very much part of the contract—not described in a standard. More about the JSON data format can be found at http://www.json.org/.

Regarding XML use in REST services, XML standards and conventions are really not in play other than to utilize syntactically correct tags and text. In particular, namespaces are not, nor should they be use in a RESTful service context. XML that is returned is more JSON like—simple and easy to read, without the schema and namespace details present—just data and links.

Create Fine-Grained Resources