WolMo - Networking iOS
WolMo - Networking iOS is a framework which provides an easy customizable HTTP request and session manager for iOS commonly used at Wolox.
Table of Contents
Carthage is a dependency manager that builds your dependencies and provides you with binary frameworks.
You can install Carthage with Homebrew using the following command:
brew update brew install carthage
To download wolmo-networking-iOS, add this to your Cartfile if you are using Swift 3.2 or 4:
github "Wolox/wolmo-networking-ios" "swift-3.2-compatibility"
Or if you are using an older version of Swift:
github "Wolox/wolmo-networking-ios" "master"
Bootstrap the project and then drag it to your workspace.
The framework provides an easy way to build HTTP repositories to perform requests to a given API based on Alamofire. The authentication method is based in a token provided in the HTTP header under the key
Fetching an entity
In case a custom repository should fetch a single or a collection of models, they must implement
Decodable (see Argo). This way they can be automatically decoded by the framework. Check UserDemo or Entity.
In case the entity is too complex, it's possible to get the error:
Expression was too complex to be solved in reasonable time. In this case check this Argo issue for a workaround.
The basic and expected errors are implemented, and a way to add custom errors related to the project itself is provided. In order to add new errors it should be necessary to create a new
enum which implements the protocol
CustomRepositoryErrorType as done in EntityRepository and match the expected status code in the HTTP response with each custom error. An example of this can be found in EntityRepository in the function
Also, a custom
DecodeError (see Argo) can be sent manually. An example can be found in EntityRepository in the function
fetchEntities. This is useful in case the response body does not match exactly the return type and some kind of decoding needs to be manually performed.
Error decoding reporting
In case a
DecodeError is get, the framwork offers a way to perform an action (for example reporting the error using a third party service to notify about a mismatch between API and the client).
To do this provide a closure
DecodedErrorHandler. Check DecodedExtension. This closure receives the
Argo.DecodeError and returns
Creating a repository instance
When creating a repository instance it expects an instance of NetworkingConfiguration, which is the struct intended to be the only place where the API settings are configured.
The properties configurable from there are:
http. In case this is disabled, the proper exception must be added to
Info.plistfile in the project.
domainURL: String: API domain.
port: String: API port.
subdomainURL: String: API subdomain (optional parameter). This URL must start with
/as required by
usePinningCertificate: Bool: enables SSL Pinning (false by default) (see next section).
Enable SSL Pinning
If enabling SSL pinning a valid
.der certificate must be provided. It needs to be added to the project and be present in "copy bundle resources" phase. The framework will automatically look for any certificate provided in bundle and use it.
The framework provides a SessionManager intended to manage the current session. It also stores the user session exposing a way to update it whenever the user logs in, logs out, updates and expires. These transitions are expected to be handled outside the framework, but always letting SessionManager know about them.
When a user is logged in or signed up,
login: must be called providing the fetched user. This will make
SessionManager know a valid session is being used, and the session token will be injected in every request for authentication.
The same way, when the user is logged out,
logout must be called. This will make
SessionManager remove the stored session token, and every request will return a
update: receiving a user can be useful to make
SessionManager store an updated
Storing a User
SessionManager can provide the current user reading the property
currentUser. This property is set when
bootstrapSession is called, which must be called only once.
This function fetches the current user if an instance of CurrentUserFetcherType is provided. Since the user is not persisted in the device, and only stored in memory the user needs to be fetched every time the application is launched.
AlamofireNetworkActivityLogger (see AlamofireNetworkActivityLogger) can be enabled by doing
NetworkActivityLogger.shared.startLogging(). This will log in the console every request and response made depending on the
logLevel, which can be selected by assigning the property
NetworkActivityLogger.shared.level with a value of
NetworkActivityLoggerLevel. By default, it enables it in debug.
Check NetworkingDemoLauncher for an example.
NetworkActivityIndicatorManager (see NetworkActivityIndicatorManager) is available to be enabled directly by doing
NetworkActivityIndicatorManager.shared.isEnabled = true to automatically mananger the visibility of the network activity indicator.
Check NetworkingDemoLauncher for an example.
git clone email@example.com:Wolox/wolmo-networking-ios.git cd wolmo-networking-ios script/bootstrap
- Fork it
Bootstrap using the forked repository (instead of
- Create your feature branch (
git checkout -b my-new-feature)
- Commit your changes (
git commit -am 'Add some feature')
- Run tests (
- Push your branch (
git push origin my-new-feature)
- Create a new Pull Request
WolMo - Core iOS is available under the MIT license.
Copyright (c) 2016 Pablo Giorgi <firstname.lastname@example.org> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.