merge conflict

Author: dgottlieb

index.rst

@@ -54,6 +54,9 @@ Congratulations, you just made your first Fiesta API request ☺.
 Next Steps
 ----------
 
+Developers should start by checking out the Fiesta :doc:`sandbox`,
+which allows testing and experimentation in a low-impact environment.
+
 The next step for developers is to learn about how Fiesta handles
 :doc:`authentication` for API clients.
 
@@ -77,6 +80,7 @@ contributing check out the source on `Github
 .. toctree::
    :hidden:
 
+   sandbox
    authentication
    list-management-api
    message-middleware-api

list-management-api.rst

@@ -53,7 +53,7 @@ group. We'll start with :http:post:`/group`:
       {
         creator: {
                    address: EMAIL_ADDRESS,
-                   group_name: STRING (optioal),
+                   group_name: STRING (optional),
                    display_name: STRING (optional),
                    welcome_message: WELCOME_MESSAGE (optional)
                  } (optional),
@@ -73,11 +73,12 @@ group. We'll start with :http:post:`/group`:
     (e.g. "[email protected]"). This address must be owned by the
     authenticated user.
 
-    `group_name` (optional) is the group name that will be used for 
-    the group's creator. If you're creating a list called 
-    "family\@fiesta.cc", `roup_name` should be "family". `Group_name`
-    may be omitted if and only if a `default_group_name` is specified
-    in which case the `default_group_name` will be used.
+    `group_name` (optional) is the group name that will be used for
+    the group's creator. If you're creating a list called
+    "family\@fiesta.cc", `group_name` should be "family". `group_name`
+    may be omitted if and only if a `default_group_name` is specified.
+    In that case the `default_group_name` will be used. See
+    :ref:`group-names` for more information.
 
     `display_name` (optional) is the name that will be displayed for
     the group's creator throughout the Fiesta UI (e.g. "Mike
@@ -92,9 +93,10 @@ group. We'll start with :http:post:`/group`:
     creator instead. If it's ``null`` or ``false`` no welcome message
     will be sent.
 
-    `default_group_name` (optional) is the default group name members will
-    get when added to this group unless a different one is specified when
-    being added.
+    `default_group_name` (optional) is the default group name members
+    will get when added to this group unless a different one is
+    specified when being added. See :ref:`group-names` for more
+    information.
 
     `domain` (optional) is the domain to use for the list address. The
     default is "fiesta.cc". To use a custom domain your client must
@@ -178,16 +180,18 @@ was returned above:
         address: EMAIL_ADDRESS,
         group_name: STRING (optional),
         display_name: STRING (optional),
-        welcome_message: WELCOME_MESSAGE (optional)
+        welcome_message: WELCOME_MESSAGE (optional),
+        send_invite: BOOLEAN (optional)
       }
 
     `address` is the email address of the new member.
 
-    `group_name` (optional) is the group name that will be used for the 
-    new member. If you're creating a list called "family\@fiesta.cc",
-    `group_name` should be "family". `Group_name` may be omitted if
-    and only if a `default_group_name` exists for the list in which
-    case the `default_group_name` will be used.
+    `group_name` (optional) is the group name that will be used for
+    the new member. If you're creating a list called
+    "family\@fiesta.cc", `group_name` should be "family". `group_name`
+    may be omitted if and only if a `default_group_name` exists for
+    the list. In that case the `default_group_name` will be used. See
+    :ref:`group-names` for more information.
 
     `display_name` (optional) is the name that will be displayed for
     the new member throughout the Fiesta UI. If it's included and the
@@ -201,6 +205,14 @@ was returned above:
     instead. If it's ``null`` or ``false`` no welcome message will be
     sent.
 
+    If `send_invite` is ``True`` (the default is ``False``), the new
+    member will be invited to the list but not added. They'll receive
+    an email invitation with a link they can click to join the
+    list. If `send_invite` is ``True`` and a custom `welcome_message`
+    is specified, the welcome message must contain the string
+    ``"$invite_url"``, which will be replaced with the URL the user
+    can click to join the group.
+
     Returns the following JSON data in the response body:
 
     .. code-block:: js
@@ -244,6 +256,28 @@ was returned above:
 
     `group_name` is the name of the group as used by this user.
 
+.. _group-names:
+
+Notes on Group Names
+--------------------
+
+Group names may only contain letters, numbers, '-', '_', and '.'. The
+maximum length of a group name is 30 characters. Names are not case
+sensitive and '-', '_', and '.' are ignored for the purposes of
+equality testing. So ``"test"``, ``"t_e_s_t"`` and ``"Te.ST"`` are
+considered equivalent.
+
+When adding someone to a list with a specific group name, the name
+they are actual added with may differ: Fiesta will automatically
+ensure that the name is unique among all of their lists. If
+[email protected] already has a list called "family" and your client
+attempts to add them to another list using the name "family" the new
+list will automatically be renamed to "family1" for that user.
+
+The group namespace is shared across all domains. If you are using a
+custom domain the same collision response will occur with groups of
+the same name using a different domain.
+
 Sending Messages
 ----------------
 
@@ -505,3 +539,56 @@ Getting Group/User Information
 
    Responds with a status code 200 if the memberships were 
    successfully deleted.
+
+Errors
+------
+
+Any API error will result in a response with a 40x HTTP status
+code. Error responses also contain a JSON body, e.g.:
+
+.. code-block:: js
+
+  {
+    status: {code: 400},
+    error: "invalid_request",
+    error_description: "Unsupported Authorization scheme"
+  }
+
+`status` will always be present, and contains a `code` field whose value will always match the HTTP status code of the response.
+
+`error` will always be present, and is a short token categorizing the error (see below for a list of possible values).
+
+`error_description` will sometimes be present, and is a long-form description of the error that occurred.
+
+List of possible `error` values:
+
+- ``"invalid_request"`` (400): The client sent a request that is
+  malformed or missing required values.
+
+- ``"invalid_scope"`` (400): The client requested authorization for a
+  scope that isn't recognized by the API.
+
+- ``"unsupported_grant_type"`` (400): The client is attempting to use
+  an unsupported OAuth grant type.
+
+- ``"invalid_token"`` (401): The API call was made using an invalid or
+  expired token.
+
+- ``"invalid_client"`` (401): The API call was made using invalid
+  client credentials.
+
+- ``"access_denied"`` (401): The client does not have sufficient
+  permissions to make the attempted request.
+
+- ``"no_such_resource"`` (404): The client is attempting to operate on
+  a resource (e.g. group, user, etc.) that does not exist.
+
+- ``"unsupported_response_type"`` (406): The client requested a
+  response type (using the Accept header) that isn't supported by the
+  API.
+
+.. note:: It's possible (though unlikely) that an attempt to use the
+   API could result in a 50x response. Any such response is
+   automatically reported so we can attempt to address the issue, but
+   following up with any helpful information about the error is
+   appreciated.

sandbox.rst

@@ -0,0 +1,74 @@
+API Sandbox
+===========
+
+We maintain an API "sandbox" at ``sandbox.fiesta.cc``. This allows API
+clients to test interacting with Fiesta, without actually sending any
+emails or modifying any real groups or user accounts.
+
+Usage
+-----
+
+To use the sandbox, just replace all references to ``api.fiesta.cc``
+with ``sandbox.fiesta.cc``. Your client will still need to
+authenticate, and you'll use the same credentials as you would with
+the production API server. All calls should still use HTTPS.
+
+Special Endpoints
+-----------------
+
+The sandbox supports several endpoints that aren't present in the
+production API:
+
+.. http:get:: /mailbox
+
+   Get information about the messages that would have been sent as a
+   result of your API calls, had this been running out of the sandbox.
+
+   Returns a JSON array with keys for each email address that has been
+   messaged. The values are arrays of messages, each with a ``"text"``
+   and ``"subject"`` field:
+
+   .. code-block:: js
+
+     {
+       mike@corp.fiesta.cc: [
+         {
+           text: "Hello world.",
+           subject: "Saying hello"
+         },
+         ...
+       ],
+       ...
+     }
+
+.. http:post:: /reset
+
+   Reset any sandbox state changes made by your client.
+
+   This will empty your client's "mailbox" and remove any sandbox
+   groups or users that have been created as a result of your client's
+   calls.
+
+   Response:
+
+   .. code-block:: js
+
+     {
+       "reset": true
+     }
+
+Notes
+-----
+
+The sandbox does share some state among clients, so it's possible to
+see some changes in behavior based on activities of other clients.
+
+In the sandbox, clients can use any `Fiesta Custom
+<https://fiesta.cc/custom>`_ domain that they want. In production,
+clients must have permission to use a Fiesta Custom domain: the
+client's owner must be an owner of the domain.
+
+Sandbox state should be treated as temporary. We will try to only
+erase state after days of inactivity or an explicit call to
+:http:post:`/reset`, but we reserve the right to erase any sandbox
+state at any time if it makes our lives significantly easier :).