Quaderno

Quaderno is a Swift framework that provides easy access to the Quaderno API.

Why Using It?

You can implement your own client for the Quaderno API. However, using quaderno-swift gives you instant access to the same interface without the details of HTTP requests and responses.

Note that you need a valid account to use Quaderno.

Supported OS & SDK Versions

• Supported build target - iOS 10.x, macOS 10.12
• Earliest supported deployment target - iOS 9.0, macOS 10.11
• Earliest compatible deployment target - iOS 9.0, macOS 10.11

'Supported' means that the library has been tested with this version. 'Compatible' means that the library should work on this OS version (i.e. it doesn't rely on any unavailable SDK features) but is no longer being tested for compatibility and may require tweaking or bug fixes to run correctly.

Installation

Add Quaderno to your Podfile if you are using CocoaPods:

pod "Quaderno", "~> 2.0"

Or to your Cartfile if you are using Carthage:

github "Quaderno/Quaderno" "~> 2.0"

Otherwise just drag the .swift source files under the Source directory into your project.

Embedded frameworks require a minimum deployment target of iOS 8.

To use Quaderno with application targets that do not support embedded frameworks, such as iOS 7, you must include all source files directly in your project.

Usage

In order to make requests you need to instantiate at least one Client object, providing a base URL for building resource paths and your authentication token:

let client = Client(baseURL: "https://quadernoapp.io/api/v1/", authenticationToken: "your token")

All requests are done asynchronously, as explained in Alamofire's README.

Importing the Module

Import the Quaderno module as you would normally include any Swift module:

import Quaderno

Checking the Service Availability

You can ping the service in order to check whether it is available:

let client = Client(baseURL: "https://quadernoapp.io/api/v1/", authenticationToken: "your token")
client.ping { error in
  // error will be nil if the service is available.
}

Fetching the Account Credentials

You can fetch the account credentials for a given user:

let client = Client(baseURL: "https://quadernoapp.io/api/v1/", authenticationToken: "your token")
client.account { result in
  // result will contain either an error or a JSON object with the account information.
}

See the "Authorization" section on the Quaderno API for further details.

Requesting Resources

You can request any supported resource using the send(_:completion) function:

let client = Client(baseURL: "https://quadernoapp.io/api/v1/", authenticationToken: "your token")

let request = Contact.request(.read(48))
client.send(request) { response in
  // response will contain either an error or the response to the request.
}

The first parameter must be an object conforming to the Request protocol.

For convenience, Quaderno already provides a set of default resources (ContactResource, InvoiceResource,…) that adopt Request and provide requests for common behaviours (CRUDResource, DeliverableResource,…). For further details check also Resource protocol.

The second parameter is a closure that receives a generic Response as only parameter. The type of the response is inferred at compilation depending on what you provide. Quaderno will try to cast the response received by the server to the type you indicate:

let client = Client(baseURL: "https://quadernoapp.io/api/v1/", authenticationToken: "your token")

let request = Contact.request(.read(48))
client.send(request) { (response: Response<[String: Any]>) in
  // response will contain either an error or a dictionary.
}

Connection Entitlements

You can check the entitlements for using the service (e.g. the rate limit) by inspecting the entitlements property of Client.

See the Client.Entitlements struct for further details.

Persistence

Quaderno does not automatically persist your objects for you.

Development

Getting Started

Quaderno uses Carthage to manage dependencies. See Cartfile and Cartfile.private to see the current dependencies.

After cloning this repository run the following commands:

carthage bootstrap

Project Structure

The entry point for the project is the Quaderno.xcodeproj file, which contains two targets and their testing counterparts:

1. Quaderno iOS, for building on iOS platforms.
2. Quaderno macOS, for building on macOS platforms.

Documentation

The source code is fully documented using the markup formatting commands defined by Apple.

More Information

Remember that this is only a Swift wrapper for the original API. If you want more information about the API itself, head to the original API documentation.

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct, as defined by contributor-covenant.org. By participating in this project you agree to abide by its terms.

Credits

Quaderno has been originally developed by Eliezer Talón.

Contact

Follow Quaderno (@quadernoapp) on Twitter.

License

Quaderno is released under the MIT license. See LICENSE.txt.