Swiftpack.co - DZNS/DZNetworking as Swift Package

Swiftpack.co is a collection of thousands of indexed Swift packages. Search packages.
See all packages published by DZNS.
DZNS/DZNetworking v0.0.1
Simple NSURLSession wrapper and additional convenience classes.
⭐️ 4
🕓 1 year ago
.package(url: "https://github.com/DZNS/DZNetworking.git", from: "v0.0.1")

DZNetworking

Carthage compatible Xcode CI

NSURLSession based networking using PromiseKit.

DZNetworking exposes simple APIs that make networking with REST APIs simple. The API is straight-forward, well tested and extensible. DZNetworking utilizes PromiseKit to provide a promises based API and OMGHTTPURLRQ for creating NSURLRequests. Thus, DZNetworking should be treated as a simple wrapper around NSURLSession for PromiseKit.

Here's a quick example of a GET request, right from the test suite:

[_session GET:@"/posts/1" parameters:nil]
.thenInBackground(^(DZResponse *responded) {
    
    // ... handle the response
        
})
.catch(^(NSError *error) {
	// ... any errors thrown during the process of creating the request, 
	// networking or parsing the response will invoke this block.
});

--

Chaining

As you will see, Promises vastly reduce the possibility of introducting Spaghetti code in your source files. You can chain requests as follows:


[_session GET:@"/resource"]
.thenInBackground(^(DZResponse *responded) {
	
	return [_session POST:@"/resource/new"]
	
})
.thenInBackground(^(DZResponse *responded) {
	
	return [_session PATCH:@"/resource/200"]
	
})
.thenInBackground(^(DZResponse *responded) {
	
	// ... handle the response of the previous PATCH request.
	
})
.catch(^(NSError *error) {
	// ... any errors thrown during the process of creating the request, 
	// networking or parsing the response will invoke this block.
});

Chaining is not limited to networking requests and methods provided by DZNetworking. Any method that returns a AnyPromise is ready to be chained.

Installing

The recomended method to install DZNetworking is via Carthage.

Add the following to your Cartfile

github "dzns/DZNetworking" 

Don't forget to run carthage update and then following the instructions here to add DZNetworking under the frameworks path.

Instantiating

DZURLSession makes it really easy to get started. Here's a sample:

self.session = [[DZURLSession alloc] init];
self.session.baseURL = [NSURL URLWithString:@"http://api.myapp.com/"];
self.session.responseParser = [DZJSONResponseParser new];

-- The DZJSONResponseParser is a subclass of DZResponseParser which handles parsing JSON responses. You can implement your own response parsers (example: XML, YAML, etc.) by subclassing DZResponseParser and implementing the following two compulsory methods:

- (id)parseResponse:(NSData *)responseData :(NSHTTPURLResponse *)response error:(NSError **)error;
- (NSSet *)contentTypes;

You must then assign that response parser to the DZURLSession before making network requests.

--

The DZURLSession class has been configured to automatically use the DZActivityIndicatorManager. You can turn this off by setting NO on the useActivityManager property.

--

The DZURLSession class also comes with requestModifier block. This is useful when you need to modify all or most requests in a similar fashion before they are sent over the wire. A good use-case would be appending oAuth headers/query parameters to requests. This leaves your networking methods in your subclass clean and easibly debuggable.

--

Documentation

We've tried our best to document most headers properly. If you believe you require clarifcation on something, please open an issue, appropriately tagged, and we'll try to either:

  • include documentation, if missing.
  • improve documentation, if incorrect.
  • try to answer the issue in the thread, if already correctly documented.

--

You can also generate HTML documentation using AppleDocs.

  • First, install appledocs if you haven't already.
  • Run the gendocs command file in terminal.

When running gendocs, it'll automatically open the generated documentation in the default browser. If this behaviour is undesirable, you can pass the -n or --no-open flag to prevent that.

--

Autocompletion

The .thenInBackground() method is from PromiseKit. PromiseKit allows resolving with Tuples which is what DZNetworking uses. However, typing the success syntax: .thenInBackground(^(DZResponse *responded) {}) can quickly become tiresome. To aide you, we've also included two autocomplete snippets, one for the success and the other for the error block. You can find them in the Autocomplete Snippets folder.

To install, simply copy them over to the ~/Library/Developer/Xcode/UserData/CodeSnippets/ folder. If the CodeSnippets folder does not exist, simply create it.

The success handle can be triggered by the thenOnSuccess shortcut and the error handler by the catchError shortcut.

--

Supported HTTP Methods

  • HEAD
  • OPTIONS
  • GET
  • POST
  • PUT
  • PATCH
  • DELETE

--

ToDo

  • File Uploads
  • Multi-part POST
  • Authentication challenge handling

--

Pull Requests & Issues

If you'd like to contribute, please open a Pull Request. If you have any issues, please open an Issue. Don't forget to tag it appropriately, and be nice to others.

--

LICENSE

DZNetworking is licensed under the MIT License. Complete information can be found in the License file.

GitHub

link
Stars: 4
Last commit: 1 week ago
jonrohan Something's broken? Yell at me @ptrpavlik. Praise and feedback (and money) is also welcome.

Release Notes

PromiseKit 3.0 and OMGHTTPURLRQ 3.0.2
7 years ago

Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics