SFRestAPI (Blocks) Category

For receiving and handling REST API responses, you can use inline code blocks instead of a delegate class. This alternative Objective-C approach lets you send a request and handle its asynchronous response in a single method call.

Mobile SDK for native iOS provides block methods for single requests, composite requests, and batch requests. When you use these methods, you provide block arguments to handle success and failure responses. Mobile SDK forwards the asynchronous response to your success or failure block according to the response’s network status.

Block methods and associated typedefs are defined in the SFRestAPI (Blocks) category as follows:

1// Sends a single request you've already built, using blocks to return status. 
2- (void) sendRequest:(SFRestRequest *)request 
3        failureBlock:(SFRestRequestFailBlock)failureBlock 
4        successBlock:(SFRestResponseBlock)successBlock 
5        NS_REFINED_FOR_SWIFT;
6
7// Sends a composite request you've already built, using blocks to return status.
8- (void) sendCompositeRequest:(SFSDKCompositeRequest *)request 
9                 failureBlock:(SFRestRequestFailBlock)failureBlock 
10                 successBlock:(SFRestCompositeResponseBlock)successBlock 
11                 NS_REFINED_FOR_SWIFT;
12
13// Sends a batch request you've already built, using blocks to return status.
14- (void) sendBatchRequest:(SFSDKBatchRequest *)request 
15             failureBlock:(SFRestRequestFailBlock)failureBlock 
16             successBlock:(SFRestBatchResponseBlock)successBlock 
17             NS_REFINED_FOR_SWIFT;

Each send method requires two blocks:

Failure Block

A failure block can receive timeout, cancellation, or error failures.

Block type:

1typedef void (^SFRestRequestFailBlock) (id _Nullable response, 
2    NSError * _Nullable e, NSURLResponse * _Nullable rawResponse) 
3    NS_SWIFT_NAME(RestRequestFailBlock);

Response type: NSError

Success Block

Block type and response type depend on the request type as follows:

Single Request

Response type: NSArray or NSData object, depending on the data returned.

Block types (use the appropriate template for your request’s return type):

1typedef void (^SFRestDictionaryResponseBlock) (NSDictionary * _Nullable dict, 
2    NSURLResponse * _Nullable rawResponse) 
3    NS_SWIFT_NAME(RestDictionaryResponseBlock); 
4
5// Use this block when you request API versions
6typedef void (^SFRestArrayResponseBlock) (NSArray * _Nullable arr, 
7    NSURLResponse * _Nullable rawResponse) 
8    NS_SWIFT_NAME(RestArrayResponseBlock);

Composite Request

Block type:

1typedef void (^SFRestCompositeResponseBlock) (SFSDKCompositeResponse *response, 
2    NSURLResponse * _Nullable rawResponse) 
3    NS_SWIFT_NAME(RestCompositeResponseBlock);

Response type: SFSDKCompositeResponse

Batch Request

Block type:

1typedef void (^SFRestBatchResponseBlock) (SFSDKBatchResponse *response, 
2    NSURLResponse * _Nullable rawResponse) NS_SWIFT_NAME(RestBatchResponseBlock);

Response type: SFSDKBatchResponse

Send a Request Using Blocks

To send a request using a block method:

Create the SFRestRequest object that fits your needs.

For a single request:

Create your SFRestRequest object by calling the appropriate SFRestAPI factory method.

Send your request. The following example handles any request that returns an NSDictionary response:

1- (void)sendRequestForDictionary:(SFRestRequest *)request {
2    // Block to handle failure 
3    SFRestRequestFailBlock failBlock = ^(id response, NSError *error, NSURLResponse *rawResponse) {
4        // Do as you wish with the error information
5        //...
6    };
7
8    // Block to handle success
9    SFRestDictionaryResponseBlock completeBlock = ^(NSDictionary *data, NSURLResponse *rawResponse) {
10        // Process the dictionary data
11        //...
12    };
13
14    // Send the request to Salesforce along with your success and failure blocks
15    [[SFRestAPI sharedGlobalInstance] sendRequest:request
16                                            failureBlock:failBlock
17                                        successBlock:completeBlock];
18...
19}

For batch and composite requests:

For each subrequest, create an SFRestRequest object by calling an appropriate factory method.

To create the SFRestRequest object that you send to Salesforce, pass an array of your subrequest objects to the batch or composite factory method. See SFRestAPI.h for more information.

1// Batch request factory method
2- (SFRestRequest *) batchRequest:(NSArray<SFRestRequest *> *)requests 
3                     haltOnError:(BOOL)haltOnError 
4                      apiVersion:(nullable NSString *)apiVersion;
5
6// Composite request factory method
7- (SFRestRequest *)compositeRequest:(NSArray<SFRestRequest *> *) requests 
8                             refIds:(NSArray<NSString *> *)refIds 
9                          allOrNone:(BOOL)allOrNone 
10                         apiVersion:(nullable NSString *)apiVersion;

Design your success block to handle the expected data.
Design your failure block to handle the issue gracefully.
Pass the SFRestRequest object you created in step 1, and your success and failure blocks, to the appropriate send block method.

For Swift, Mobile SDK refines the Objective-C block methods to funnel the REST response into a single Swift completion closure. See Handling REST Responses.
In Objective-C, judicious use of blocks and delegates can help fine-tune your app’s readability and ease of maintenance. Ideal conditions for using blocks often correspond to those that mandate inline functions in C++ or anonymous functions in Java. Ultimately, you make a judgment call based on your own requirements.

Note

Mobile SDK Development Guide

SFRestAPI (Blocks) Category

Send a Request Using Blocks

See Also