<commit_before># WebApiClient

**WebApiClient** is an application framework aimed at making RESTful web service requests in a standardized way. The project is divided into modules, staring with a **Core** module and then branching off into various supporting modules.

# Module: Core

The **Core** module provides a HTTP client framework based on _routes_ with support for _object mapping_ for transforming requests and responses between native objects and serialized forms, such as JSON. This module provides just a protocol based API and some scaffolding classes to support the API, but does not provide an actual full implementation itself, so that different HTTP back-ends can be used as needed (the **AFNetworking** module provides a full implementation).

The [WebApiClient](https://github.com/Blue-Rocket/WebApiClient/blob/master/WebApiClient/Code/WebApiClient/WebApiClient.h) protocol defines the main HTTP client entry point for applications to use. The API is purposefully simple and based on asynchronous block callbacks:

```objc
- (void)requestAPI:(NSString *)name 
 withPathVariables:(id)pathVariables 
        parameters:(id)parameters 
              data:(id<WebApiResource>)data
		  finished:(void (^)(id<WebApiResponse> response, NSError *error))callback;
```

An example invocation of this API might look like this:

```objc
// make a GET request to /documents/123
[client requestAPI:@"doc" withPathVariables:@{@"uniqueId" : @123 } parameters:nil data:nil 
          finished:^(id<WebApiResponse> response, NSError *error) {
	if ( !error ) {
		MyDocument *doc = response.responseObject;
	} else if ( response.statusCode == 422 ) {
		// handle 422 (validation) errors here...
	}
}];
```

## Background callback support

By default the callback block is called on the main thread (queue). If you prefer to have the callabck on a specific queue, you can use an alternate method that accepts a dispatch queue as a parameter. In that case, the passed in queue will be used for the callback:

```objc
- (void)requestAPI:(NSString *)name 
 withPathVariables:(id)pathVariables 
        parameters:(id)parameters 
              data:(id<WebApiResource>)data
             queue:(dispatch_queue_t)callbackQueue
		  finished:(void (^)(id<WebApiResponse> response, NSError *error))callback;
```

## Synchronous request support

Sometimes it can be useful to make a blocking, synchronous request to get a HTTP resource. WebApiClient supports that as well:

```objc
- (id<WebApiResponse>)blockingRequestAPI:(NSString *)name
                       withPathVariables:(id)pathVariables
                              parameters:(id)parameters
                                    data:(id<WebApiResource>)data
                             maximumWait:(NSTimeInterval)maximumWait
                                   error:(NSError **)error;
```

Calling this method will block the calling thread until either the response is available or `maximumWait` seconds have elapsed.

## Routing<commit_msg>Update the docs with the new progress block API.<commit_after># WebApiClient

**WebApiClient** is an application framework aimed at making RESTful web service requests in a standardized way. The project is divided into modules, staring with a **Core** module and then branching off into various supporting modules.

# Module: Core

The **Core** module provides a HTTP client framework based on _routes_ with support for _object mapping_ for transforming requests and responses between native objects and serialized forms, such as JSON. This module provides just a protocol based API and some scaffolding classes to support the API, but does not provide an actual full implementation itself, so that different HTTP back-ends can be used as needed (the **AFNetworking** module provides a full implementation).

The [WebApiClient](https://github.com/Blue-Rocket/WebApiClient/blob/master/WebApiClient/Code/WebApiClient/WebApiClient.h) protocol defines the main HTTP client entry point for applications to use. The API is purposefully simple and based on asynchronous block callbacks:

```objc
- (void)requestAPI:(NSString *)name 
 withPathVariables:(id)pathVariables 
        parameters:(id)parameters 
              data:(id<WebApiResource>)data
		  finished:(void (^)(id<WebApiResponse> response, NSError *error))callback;
```

An example invocation of this API might look like this:

```objc
// make a GET request to /documents/123
[client requestAPI:@"doc" withPathVariables:@{@"uniqueId" : @123 } parameters:nil data:nil 
          finished:^(id<WebApiResponse> response, NSError *error) {
	if ( !error ) {
		MyDocument *doc = response.responseObject;
	} else if ( response.statusCode == 422 ) {
		// handle 422 (validation) errors here...
	}
}];
```

## Background callback support

By default the callback block is called on the main thread (queue). If you prefer to have the callabck on a specific queue, you can use an alternate method that accepts a dispatch queue as a parameter. In that case, the passed in queue will be used for the callback:

```objc
- (void)requestAPI:(NSString *)name 
 withPathVariables:(id)pathVariables 
        parameters:(id)parameters 
              data:(id<WebApiResource>)data
             queue:(dispatch_queue_t)callbackQueue
          progress:(nullable WebApiClientRequestProgressBlock)progressCallback
		  finished:(void (^)(id<WebApiResponse> response, NSError *error))callback;
```

## Progress callback support

The same method that accepts an explicit callback block shown in the previous section also accepts an optional `WebApiClientRequestProgressBlock`, which is defined as this:

```objc
typedef void (^WebApiClientRequestProgressBlock)(NSString *routeName, 
                                                 NSProgress * _Nullable uploadProgress, 
                                                 NSProgress * _Nullable downloadProgress);
```

By passing in this type of block to the `progress` parameter, you can monitor both the upload and download progress of the HTTP request. In addition the `WebApiClientRequestDidProgressNotification` and `WebApiClientResponseDidProgressNotification` notifications can be used to listen for progress updates as well. The `WebApiClientProgressNotificationKey` notification user info key will contain the relevant `NSProgress` object.

## Synchronous request support

Sometimes it can be useful to make a blocking, synchronous request to get a HTTP resource. WebApiClient supports that as well:

```objc
- (id<WebApiResponse>)blockingRequestAPI:(NSString *)name
                       withPathVariables:(id)pathVariables
                              parameters:(id)parameters
                                    data:(id<WebApiResource>)data
                             maximumWait:(NSTimeInterval)maximumWait
                                   error:(NSError **)error;
```

Calling this method will block the calling thread until either the response is available or `maximumWait` seconds have elapsed.

## Routing
{'fraction_non_alphanumeric': 0.07613198114555064, 'fraction_numerical': 0.0034280817026139123, 'mean_word_length': 3.731081081081081, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 17, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 10, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1930964', 'n_tokens_mistral': 1792, 'n_tokens_neox': 1630, 'n_words': 712}