Add recommendations for asynchronous processing

Benoit Tigeot · Benoit Tigeot · commit dd0025227e2d · 2015-06-29T11:14:19.000+02:00
Started a discussion on discourse about it : http://discuss.jsonapi.org/t/long-running-jobs-or-asynchronous-processing/26 Maybe the status response have too much infos for this example. Maybe "actions" should not be there.
diff --git a/recommendations/index.md b/recommendations/index.md
@@ -142,3 +142,53 @@ that wish to support these clients are recommended to treat `POST` requests as
 `PATCH` requests if the client includes the `X-HTTP-Method-Override: PATCH`
 header. This allows clients that lack `PATCH` support to have their update
 requests honored, simply by adding the header.
+
+
+## Asynchronous Processing <a href="#asynchronous-processing" id="asynchronous-processing" class="headerlink"></a>
+
+Consider a situation when you need to create a resource and the operation takes long time to complete.
+
+The request **SHOULD** return a status `202 Accepted` with a link in Header/Location.
+
+```text
+HTTP/1.1 202 Accepted
+Location: https://example.com/photos/queue/5234
+Content-Type: application/vnd.api+json
+```
+
+The location gave **SHOULD** return `200 Ok` with the status of the selected job. The body **MAY** contains `"actions"` to manage the job.
+
+```json
+{
+  "links": {
+    "self": "/photos/queue/5234"
+  },
+    "data": {
+      "type": "queue job",
+      "id": "5234",
+      "status": "Process failed, see errors",
+      "errors": [
+      {
+        "code": "too_long",
+        "field": "/photos/title"
+      },
+      {
+        "code": "invalid_format",
+        "field": "/photos/file01"
+      }
+      ]
+    },
+    "actions": {
+        "cancel": "/photos/queue/5234/cancel",
+        "delete": "/photos/queue/5234/delete"
+    }
+}
+```
+
+When job process is done the location gave **SHOULD** return `303 See other` with the location of the data in Header/Location.
+
+```text
+HTTP/1.1 303 See other
+Location: https://example.com/photos/4577
+Content-Type: application/vnd.api+json
+```
