Asynchronous request processing

This section describes asynchronous requests and notifications, and depends on understanding the basics of Tizra POST operations.

When a series of requests are posted as a JSON Array, these are generally made into a single asynchronous request, and scheduled for execution by the server. When all the individual operations in the array have completed, the remote notification target will receive a JSON result, POST-ed to the site's notification URL.

Making a single asynchronous request

Using a typical resource management URL:

https://secure.agilepdf.com/admin-api/3fqjvu/objects/51ni5l

Request:

{
	"operation": "staging",
	"update-published-date": true,
	"allow-async": true
}

It is possible to create a multiple-operation request as well, by posting a JSON array to the object management URL.

Request URL: https://secure.agilepdf.com/admin-api/3fqjvu/objects/51ni5l

Request:

[
	{
		"operation": "update",
		"data": {
		"meta-type": "Book",
			"props": {
				"CoverImage": "\/King_Richard_III\/~~Attachments\/cover.jpg",
				"Authors": "William Shakespeare",
				"AdminTags": "drama",
				"AllowPDFDownload": "true",
				"Title": "King Richard III"
			}
		}
	},
	{
		"operation": "staging",
		"update-published-date": true,
	}
]

If you want to perform multiple operations (potentially on multiple objects), you can POST directly to the asychronous request URL.

Request URL: https://secure.agilepdf.com/admin-api/3fqjvu/requests

Request:

[
	{
		"operation": "update",
		"tizra-id": "51ni5l",
		"data": {
		"meta-type": "Book",
			"props": {
				"CoverImage": "\/King_Richard_III\/~~Attachments\/cover.jpg",
				"Authors": "William Shakespeare",
				"AdminTags": "drama",
				"AllowPDFDownload": "true",
				"Title": "King Richard III"
			}
		}
	},
	{
		"operation": "staging",
		"update-published-date": true,
		"metadata-only": true,
		"tizra-id": "51ni5l"
	}
]

The tizra-id on each request defines the target object. It would not be necessary for an operation like update-add which uses property matching to select the object to be operated on.

A single operation asynchronous request can be made in the same way.

Request URL: https://secure.agilepdf.com/admin-api/3fqjvu/requests

{
	operation: "staging",
	update-published-date: false,
	allow-async: true,
	tizra-id: "51ni5l"
}

Asynchronous request results

In principle any operation might execute asynchronously. If an request has been queued for execution, the result indicates that fact, and also notifies the application of the request's ID, and a URL from which a GET request will return the current status of the operation.

A typical asynchronous operation result would look like this:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Location: /admin-api/9p2/requests/490b5349-a723-4621-a9dc-3ce92782093e
Content-Type: application/json;charset=UTF-8
Vary: Accept-Encoding
Date: Wed, 19 Feb 2014 02:38:06 GMT

{
	"id":"490b5349-a723-4621-a9dc-3ce92782093e",
	"status":200,.
	"message":"Submitted",
	"location":
		"\/admin-api\/9p2\/requests\/490b5349-a723-4621-a9dc-3ce92782093e"
}

The Location header indicates the URL for status checking on a request. Polling to determine completion is not necessary, since a notification mechanism is in place, but progress checking and confirmation of the existence of a request can be easily done by use of this URL.

The "id" is a unique identifier assigned to each request by the server.

Request results are posted to the remote notification URL, configured in a site's advanced site properties.

A completed request will look like this:

Here's a sample result as they would be right now:
{
	"result":
	{
		"message":"Operation Complete. Check result for details.",
		"status":200,
		"original-request":
		{
			"operation":"staging",
			"allow-async":true
		},
		"site-id":10001,
		"object-id":244048,
		"result":[
			{"body":{"status":200}}
		]
	}
}

site-id and object-id can be ignored. If multiple operations were requested a single asynchronous operation, the results array would have a results record for each of the requests, in the order they were submitted (and executed). Each result element is the same as would be returned from an individual operationl, and so the results can be used for checking error returns and the like.

The result from the request URL of a completed operation looks like this:

{
    "id": "d8ba195a-d742-4117-82c8-a181d0d31161", 
    "value": {
        "message": "Operation Complete. Check result for details.", 
        "object-id": 1118909, 
        "original-request": {
            "allow-async": true, 
            "operation": "staging"
        }, 
        "result": [
            {
                "body": {
                    "status": 200
                }
            }
        ], 
        "site-id": 10001, 
        "status": 200
    }
}

Request re-scheduling in case of failure to complete

The server operation queue is not currently a persistent queue, so if an operation is significantly delayed, it may make sense to poll the server to make sure that the operation is still scheduled. This can be done by access to the request-status URL returned when an asychronous request is scheduled.

If an asynchronously scheduled operation is no longer on the server, it probably need to be rescheduled, at least in part, as the chance that the entire operation completed is small. (This can happen only in the case of some kind of failure in the gap between completion of teh request and delivery of the remote notification). Remote notifications are queued persistently and are retried over a relatively long period.

In the (more likely) case of partial execution of a request, or of a notification failure is possible, the correct restart can be determined by rechecking modification and publication dates for the resources affected by the request.