How to Request an Asynchronous REST service

Web Services

Trail: PROIV Documentation > Administration > Control Panel > Managing RESTful Web Services > Request for a Asynchronous RESTful Web Service

Client Requests for an Asynchronous REST service

1. The Initial Service Request

The client code to call an asynchronous service is the same as for a synchronous service except for a request header property. The REST server will look for the request header property called ‘Operation-Type’ and if it has the value of ‘async’ then the service will be processed asynchronously. Any other values will cause the service to be processed synchronously. If the header is not present, then the service will be processed synchronously.

A request for an asynchronous service will return the response immediately and it will have a status code of 202 (Accepted). There will be JSON code in the response body with three fields. These are:

GUID – An ID for the asynchronous service.

Status – The status of the asynchronous service (In Progress).

SerialNumber – A number that must be sent back to the server on the next request for this service.

2. Service Status Requests

The client can now send any number of status requests to find out if the service is complete. These requests must use the following URI:

/servicerequest/<GUID>/status?SerialNumber=<SERIALNUMBER>

The <GUID> must be the service id returned in the initial response. The <SERIALNUMBER> is the last serial number returned by the server. Note that a different serial number is returned by the server on each request and you must use the last one you received. This is a security feature to stop network spoofing.

The status request must use a request method of ‘GET’ no matter what request method was used in the original service request.

The response to this request will have a status code of 200 (OK) and will have the same JSON fields in the response body as the initial request (see above).

If the response Status field is ‘In Progress’ then the service is still being processed.

3. Service Completion

When a service status request is received and the service is complete then a different response is returned. The response now has a status of 303 (See Other) and will have a response header called ‘Location’ that holds the URI that must be sent in a request using a request method of ‘GET’, to get the service result. This URI will look like that below. The client should not create its own version of this URI, it must use the one in the ‘Location’ header.

/servicerequest/<GUID>/results?SerialNumber=< SERIALNUMBER >

The response to this request will be exactly the same as that for a synchronous service request (i.e. the results from the service). Note that this may be an error response if the service failed for any reason just as it would be if a synchronous service request failed.

Security Considerations

The status and results requests must return the correct GUID and serial number each time. The GUID is always the same for an asynchronous service request but different each time a new asynchronous service is started. The serial number changes each time the server responds to a request.

Both the GUID and the serial number must be correct before the server will send an OK response. Note that the serial number ‘belongs’ to a GUID so you must keep track of the latest serial number for each asynchronous service that is currently executing.

• If the GUID is not valid for a currently executing or complete asynchronous service, then the server will respond with a response status of 410 (Gone).

• If the GUID is valid but the serial number is not correct, then the server will respond with a response status of 401 (Unauthorized) and will mark the service as blocked which means that it will be allowed to complete but will not be available to any more status or result requests from the client and the service results will be discarded when the service completes.

The serial number stops another process from spoofing access to the service. Any attempt to access a service with an incorrect serial number will mean that the service immediately becomes unavailable to any future access even if that access has the correct serial number.

Asynchronous Service Timeout

After an asynchronous service is completed, the result is stored on disk on the server. When the results are collected by the client the disk files are removed, so the results can only be collected once. If the client never collects the results, then the disk will start to fill up. To stop this happening, there is a timeout period defined for all asynchronous services.

When an asynchronous service completes its timeout period starts. If the results have not been collected when the timeout period ends, then the disk files are removed and the service discarded. Subsequent attempts by the client to get the status or results will return a response status of 410 (Gone).

The timeout period is defined in the web.xml file as an init parameter called restful_async_expire_time in the NorthgateWebServices servlet, for the PROIV Web Services application and is in seconds. The default is 600 (10 minutes). A timeout of 0 means ‘no timeout’. If the value is changed then the PROIV Web Services must be restarted for the new value to be used.

REST Server Start up

When the REST server is started, it will clear the folder holding asynchronous service results. This means that any asynchronous service that was active (either in progress or complete but not collected) at the time the REST server was stopped will be lost.

CORS and Access Control

Running a REST service asynchronously will use the same CORS (Cross-Origin Resource Sharing) and security settings (Access Control) as a service run synchronously. This includes the status and results requests. This means that any status or results request to an asynchronous service must conform to the same CORS and security settings as the original service request.

Logging

The REST server includes logging to a log file called restservices.log and by default this log will only contain error messages caused by executing REST services. This logging can be changed by editing the log level in the log4j2.xml configuration file to one of the levels shown as follows:

The PROIV Web Services must be restarted for the new configuration to be used.

Comment on this topic

Topic ID: 400046