From ac19529169271bbf0183228f378a20533fddaced Mon Sep 17 00:00:00 2001 From: Christopher Downard Date: Tue, 11 Nov 2014 13:09:40 -0700 Subject: [PATCH] Fixed typo in verbiage and altered sentence to increase clarity of idea. --- lessons/restquicktips.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lessons/restquicktips.html b/lessons/restquicktips.html index 7029006..ec53e95 100644 --- a/lessons/restquicktips.html +++ b/lessons/restquicktips.html @@ -79,7 +79,7 @@
  • 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.
  • Use plurals in URL segments to keep your API URIs consistent across all HTTP methods, using the collection metaphor.
    • -
  • Avoid using collection verbage in URLs. For example 'customer_list' as a resource. Use pluralization to indicate the collection metaphor (e.g. customers vs. customer_list).
    • +
  • Avoid using collection verbiage in URLs. For example 'customer_list' as a resource. Use pluralization to indicate the collection metaphor (e.g. customers vs. customer_list).
  • Use lower-case in URL segments, separating words with underscores ('_') or hyphens ('-'). Some servers ignore case so it's best to be clear.
  • Keep URLs as short as possible, with as few segments as makes sense.
    • @@ -111,7 +111,7 @@

    Offer Both JSON and XML

    -

    Favor JSON support unless you're in a highly-standardize and regulated industry that requires XML, Schema validation and namespaces. And unless the costs of offering both JSON and XML are staggering, however, offer them both. Ideally, let consumers switch between using the HTTP Accept header, or by just changing an extension from .xml to .json on the URL.

    +

    Favor JSON support unless you're in a highly-standardized and regulated industry that requires XML, Schema validation and namespaces. And offer both JSON and XML unless the costs are staggering. Ideally, let consumers switch between using the HTTP Accept header, or by just changing an extension from .xml to .json on the URL.

    Be warned though, as soon as we start talking about XML support, we start talking about schemas for validation, namespaces, etc. Unless required by your industry, avoid supporting all that complexity initially, if ever. JSON is designed to be simple, terse and functional. Create your XML to look like that if you can.

    In other words, make the XML that is returned more JSON-like: simple and easy to read, without the schema and namespace details present—just data and links. If it ends up being more complex than this, the cost of XML will be staggering. In my experience nobody uses the XML responses anyway over the last several years. It's just too expensive to consume.

    Note that JSON-Schema offers schema-style validation capabilities, if you need that sort of thing.