If your RESTful web API takes a considerable amount of time to finish the job and the users cannot wait for the API to finish, you may want to consider using the asynchronous mode of execution.

The asynchronous RESTful web API works as explained here. The client calls the asynchronous RESTful API as any other API:

POST /employees HTTP/1.1  
[{"departmentId": 10, "departmentName": "IT"},  
{"departmentId": 20, "departmentName": "HR"},...]  

The asynchronous API that is responsible for handling the preceding request accepts the request and returns the 202 Accepted status to the caller without keeping the caller waiting for the request to finish. The response also can have a temporary resource inside the Location header, which can be used by the client to query the status of the process. Here is an example of the response generated by the server:

HTTP/1.1 202 Accepted  
Location: /queue/job1234 

The JAX-RS 2.x specification allows you to build asynchronous APIs via the following two classes:

• javax.ws.rs.container.AsyncResponse: This interface gives you a means for asynchronous server-side response processing
• @javax.ws.rs.container.Suspended: This annotation is used for injecting a suspended AsyncResponse object into a parameter of an invoked JAX-RS resource

To learn how to build an asynchronous RESTful web API with the JAX-RS APIs, refer to the Asynchronous RESTful web services section in Chapter 4, Advanced Features in the JAX-RS APIs.