The civilized way to write REST API clients for iOS / macOS
This release includes the last planned API changes for Swift 2.x. Barring the discovery of serious API design flaws, Swift 2 work from now on will be bug fixes only.
A preview of Swift 3 compatibility is now available on the swift3
branch. Grab that beta and hop on the ride! A wild oscillation between delight and apoplexy awaits. See the release plans for goals & timeline, and subscribe to #103 for status updates.
Entity.headers
is now public. (#107)ResourceStatusOverlay
and RemoteImageView
, are now separate from the Siesta core API:
SiestaUI
framework. You will need to include that framework separately in your project, and add import SiestaUI
in your code.pod 'Siesta/UI'
to your Podfile
. However, due to limitations of Cocoapods, you will still import Siesta
for UI helpers and core API alike.Request.onCompletion
now takes a ResponeInfo
struct instead of just a Response
. Where your existing onCompletion
hook uses $0
, replace it with $0.response
.skipWhenEntityMatchesOutputType:
option is gone, without an exact replacement. See #100.EntityCache
, which should open the door to much more creative and interesting persistent local mirroring of API data. Thanks to @jordanpwood for helping think through this tricky work. (Extensive writeup in #95; see also #89, #90)
Extensions/ReactiveCocoa
. Kick the tires and send feedback. Thanks to @akaralar for coding this and seeing it through! (#71)Service
methods with baseURL
and absoluteURL
parameters all now accept both String
and NSURL
. Good idea, @jordanpwood. (#74, #77)Service.resource(baseURL:path:)
to better support APIs without a clear single baseURL
. Thanks to @Reedyuk and @nikolay-dementiev for the use cases. (#94, #91, #84)GithubBrowser
example project (#76)ResourceStatusOverlay
now correctly updates its state when it stops observing a resource. (#75)ResourceStatusOverlay
can now be wired up to custom views in a storyboard. (See Breaking Changes below.) (#85, #4)Resource.withParam(…)
now correctly escapes +
in query strings. Thanks, @vvondra, for finding & fixing this. (#97, #96)EntityCache
protocol have changed, and several defunct helper types have gone away. See #95 for migration instructions.PipelineStage
now has write-only cacheUsing(_:)
and doNotCache()
methods instead of a cache
property.ResourceStatusOverlay
no longer has a BOS
prefix. Storyboards have trouble working with classes whose Swift and Objective-C names are different. This is apparently an Apple bug; dropping the prefix is a workaround.Service.configureTransformer(...)
now replaces any transformers for the model
stage with the new one instead of appending it to the end of the entire pipeline. This means that if multiple configuration blocks for the same resource call configureTransformer(...)
, the last one wins. This better matches typical user needs; if you want the old behavior, pass replaceExisting: false
.ResponseContentTransformer
no longer skips the transform when the input type already matches the output type. (For example, if the transformer returned a string but there was already a string from upstream in the pipeline, it wouldn’t run.) This behavior is useful but confusing, and shouldn’t be the default. You can enable it with skipWhenEntityMatchesOutputType: true
.EntityCache
protocol has changed. You will need to update your custom cache implementation to accept byte keys instead of string keys.?
to match single characters. This makes it easier to distinguish /items/
(with a trailing slash) from /items/1
. (#55)NSRegularExpression
as a pattern to Service.configure(…)
methods. (#47)Resource.failedRequest(…)
. This allows custom pre-validation of requests before they touch the network. Thanks, @VDKA! (#44, #50)@warn_unused_result
and @noescape
where appropriate throughout the API.pod try
. (#58)configureTransformer
no longer return double optionals.The flavor of Service.configure(...)
that takes a predicate closure now requires a whenURLMatches:
argument label:
// Before
service().configure({ $0.path.hasSuffix("foo") }) { ... }
// After
service().configure(whenURLMatches: { $0.path.hasSuffix("foo") }) { ... }
It was not possible to add a deprecation warning for this change because the deprecated form causes an ambiguous method overloading.
Because it only concerned calls bridged from Objective-C, Error.Cause.InvalidRequestMethod
has moved out of the public Swift API and into the Objective-C bridging API.
API elements deprecated in 1.0 beta 6 have now been removed.
As with all 1.0 beta releases of Siesta, this code is suitable for production use, but is marked “beta” in order to reserve the right to make API adjustments before the official 1.0 release.
Prompted by the upcoming 1.0 API freeze and the release of Apple’s new guidelines for Swift APIs, we undertook a complete review of naming choices in Siesta’s API. These will show up as deprecations in your Swift code; the deprecated methods will be removed in the next release. For details, see:
Unfortunately, the Objective-C migration path is not so smooth: because Xcode does not properly copy Swift deprecations to Obj-C header files, the methods that are deprecated in Swift will either silently continue to work from Obj-C code in some cases, and immediately break in others.
Methods that should only be called on the main thread now validate this as a precondition.
Methods are now marked with @warn_unused_result
whenever appropriate.
The user guide has a new section on threading, and there are numerous improvements to the API docs.
The internals of Request
and friends, which had become monolithic and unwieldy, are now broken into several small pieces. (There are no API changes associated with this refactoring.)
As with all 1.0 beta releases of Siesta, this code is suitable for production use, but is marked “beta” in order to reserve the right to make API adjustments before the official 1.0 release.
ephemeralSessionConfiguration
is now the default for Service
instances that use NSURLSession
. This is the more secure choice, and thus the better default; it also is more likely to give the desired behavior for 304s.ResourceStatusOverlay
improvements:
ResourceEvent.NewData(.Wipe)
from Objective-CBreaking Changes
Extensions
directory, and is not included in Siesta.framework
. You will need to add that source file manually if you want to use the Alamofire integration when including Siesta via Carthage, the binary release, or a git submodule. (CocoaPods users are unaffected by this change.)API Changes Coming
Beta 6 will include API changes to bring Siesta into better conformance with Apple’s new Swift API guidelines. Please review the proposed changes and give your feedback.
.framework
, thanks to Apple (apparently?) fixing problems with optional framework dependencies:
Service
to use Alamofire and you are using a binary version of Siesta, you can remove it from your Cartfile
.Cartfile
yourself.pod 'Siesta/Alamofire'
to include Alamofire support.http://foo.com/**
no longer matches http://bar.com/http://foo.com/
)Service.baseURL
is nilIt is now much easier to attach ad hoc content transformation to resources. Use this to inflate models just once, instead of once per observer:
myService.configureTransformer("/widgets/*") { Widget(json: $0.content) }
See Service.configureTransformer(…)
and ResponseContentTransformer
for more info. Big thanks to @radex for helping think this through!
Cleaned up error handling:
Error.cause
.NSError
in any of its APIs or internal processing.Siesta.Error
now implements ErrorType
, so you can throw it.userMessage
values generated by Siesta are now localizable.Error.isCancellation
removed favor of new error causes (i.e. error.cause is Error.Cause.RequestCancelled
).New ConfigurationPatternConvertible
lets Service.wipeResources(…)
do glob-based path matching, and lets you write your own matching mechanisms for configure(…)
and wipeResources(…)
.
Removed deprecated CFURLCreateStringByAddingPercentEscapes
call. Thanks @paddlefish!
Siesta now gives empty NSData
content instead of a request error when the network layer returns a nil response body.
Fixed: crash when trying to URL-encode strings with unpaired UTF-16 surrogate chars.
Fixed: crash when trying to use entity content with struct type from Obj-C. (It now shows up as nil.)
Fixed: leaking low memory event observer blocks.
Improved GithubBrowser example project.
Entity.content
now Any
instead of AnyObject
Siesta.Error
now implements ErrorType
contentAsType
default value is now @autoclosure