Merge pull request #381 from andymckay/docs-fixes

document overall API details. Fixes #379

docs/index.rst

@@ -39,6 +39,7 @@ Contents
 
    topics/setup.rst
    topics/security.rst
+   topics/overall.rst
    topics/auth.rst
    topics/generic.rst
    topics/bango.rst

docs/topics/overall.rst

@@ -0,0 +1,45 @@
+Overall
+-------
+
+There are things that are assumed to be true on all API requests to solitude.
+And to prevent repetition in the documentation are mentioned here.
+
+Requests
+~~~~~~~~
+
+* It's assumed that all requests are `application/json`. This isn't enforced
+  yet, but could be. If you use curling, all requests are sent with
+  `Content-Type: application/json`.
+
+* All requests should include `Accept: application/json`. If you use curling
+  this is the case.
+
+Responses
+~~~~~~~~~
+
+* It's assumed that all responses are `application/json`.
+
+* Where possible we use standard HTTP error status codes, e.g 404. If there is
+  anything unusual in the responses, we document those in the specific API
+  calls.
+
+Common elements in some responses:
+
+* `response_pk` (string): a primary key for that resource. Will be unique to
+  that resource. Example: `123`. Please note that some
+  endpoints return a value of `confirm_pin` or similar, that's
+  `a bug <https://github.com/mozilla/solitude/issues/380>`_.
+
+* `response_uri` (string): a URI to the object within solitude. To turn it
+  into a URL add the protocol and domain of the server. Example:
+  `/generic/transaction/123/`. To turn that into URL:
+  `http://solitude:2602/generic/transaction/123/`. Note: that some endpoints
+  return a value of `no_uri`, or similar, that's
+  `a bug <https://github.com/mozilla/solitude/issues/380>`_.
+
+
+Errors
+~~~~~~
+
+Errors. Consistent interface to be determined
+`by this issue <https://github.com/mozilla/solitude/issues/349>`_.

docs/topics/setup.rst

@@ -3,8 +3,14 @@
 Setup
 #####
 
-The recommended way to run solitude is in Docker. For running solitude in the
-marketplace environment, we recommend using Docker and reading the `marketplace docs <https://marketplace.readthedocs.org/en/latest/topics/backend.html>`_
+The recommended way to run solitude is in Docker.
+
+
+For running solitude in the marketplace environment, we recommend using Docker
+and reading the `marketplace docs <https://marketplace.readthedocs.org/en/latest/topics/backend.html>`_.
+
+For running solitude in the Payments for Firefox Accounts, we recommend using
+Docker and reading the `payments docs <https://payments.readthedocs.org>`_.
 
 Requirements
 ------------
@@ -149,80 +155,6 @@ Optional settings
   cleansed settings in the `django.conf.settings` through the API. Should be
   `False` on production.
 
-Getting a traceback in development
-----------------------------------
-
-There are too many options for this, but it's a commonly asked question.
-
-First off ensure your logs are going somewhere::
-
-    LOGGING = {
-            'loggers': {
-                    'django.request.tastypie': {
-                            'handlers': ['console'],
-                            'level': 'DEBUG',
-                    },
-            },
-    }
-
-
-Option 1 (recommended)
-~~~~~~~~~~~~~~~~~~~~~~
-
-Get a nice response in the client and something in the server console. Set::
-
-    DEBUG = True
-    DEBUG_PROPAGATE_EXCEPTIONS = True
-    TASTYPIE_FULL_DEBUG = False
-
-Example from client::
-
-    [master] solitude $ curling -d '{"uuid":"1"}' http://localhost:8001/bango/refund/status/
-    {
-      "error_data": {},
-      "error_code": "ZeroDivisionError",
-      "error_message": "integer division or modulo by zero"
-    }
-
-And on the server::
-
-    ...
-    File "/Users/andy/sandboxes/solitude/lib/bango/resources/refund.py", line 47, in obj_get
-        1/0
-     :/Users/andy/sandboxes/solitude/solitude/base.py:220
-    [03/Feb/2013 08:48:02] "GET /bango/refund/status/ HTTP/1.1" 500 108
-
-Option 2
-~~~~~~~~
-
-Get the full traceback in the client and nothing in the console. Set::
-
-    DEBUG = True
-    DEBUG_PROPAGATE_EXCEPTIONS = False
-    TASTYPIE_FULL_DEBUG = True
-
-On the client::
-
-    [master] solitude $ curling -d '{"uuid":"1"}' http://localhost:8001/bango/refund/status/
-    {
-            "traceback": [
-            ...
-            "  File \"/Users/andy/sandboxes/solitude/lib/bango/resources/refund.py\", line 47, in obj_get\n    1/0\n"
-            ],
-            "type": "<type 'exceptions.ZeroDivisionError'>",
-            "value": "integer division or modulo by zero"
-    }
-
-Option 3
-~~~~~~~~
-
-Get the full response in the server console and just a "error occurred" message
-on the client::
-
-    DEBUG = True
-    DEBUG_PROPAGATE_EXCEPTIONS = True
-    TASTYPIE_FULL_DEBUG = True
-
 .. _homebrew: http://mxcl.github.com/homebrew/
 .. _virtualenv: http://pypi.python.org/pypi/virtualenv
 .. _playdoh: http://playdoh.readthedocs.org/en/latest/getting-started/installation.html