Resource

The API to which this resource belongs. Provides configuration defaults and instance uniqueness.

The canoncial URL of this resource.

Configuration when there is no request method.

Configuration for requests with the given request method.

The latest valid data we have for this resource. May come from a server response, a cache, or a local override.

Note that this property represents the full state of the resource. It therefore only holds entities fetched with load() and loadIfNeeded(), not any of the various flavors of request(...).

Note that latestData will be present as long as there has ever been a succesful request since the resource was created or wiped. If an error occurs, latestData will still hold the latest (now stale) valid data.

Details if the last attempt to load this resource resulted in an error. Becomes nil as soon as a request is successful.

Note that this only reports error from load() and loadIfNeeded(), not any of the various flavors of request(...).

The time of the most recent update to either latestData or latestError.

True if any load requests (i.e. from calls to load(...) and loadIfNeeded()) for this resource are in progress.

True if any requests for this resource are in progress.

All load requests in progress, in the order they were initiated.

All requests in progress related to this resource, in the order they were initiated.

Allows callers to arbitrarily alter the HTTP details of a request before it is sent. For example:

resource.request(.post) {
  $0.httpBody = imageData
  $0.addValue("image/png", forHTTPHeaderField: "Content-Type")
}

Siesta provides helpers that make this custom RequestMutation unnecessary in many common cases. Configuration lets you set request headers, and helpers such as Resource.request(_:json:contentType:requestMutation:) will encode common request body types for you. Custom mutation is the “full control” option for cases when:

1. you need to alter the request in ways Siesta doesn’t provide helpers for, or
2. you want to alter one individual request instead of configuring all requests for a resource.

The RequestMutation receives a URLRequest after Siesta has already applied all of its normal configuration. The URLRequest is mutable, and any changes it makes are the last stop before the request is sent to the network. What you return is what Siesta sends.

Initiates a network request for the given resource.

Handle the result of the request by attaching response handlers:

resource.request(.get)
    .onSuccess { ... }
    .onFailure { ... }

See Request for a complete list of hooks.

Note that, unlike load() and loadIfNeeded(), this method does not update latestData or latestError, and does not notify resource observers about the result.

True if the resource’s local state is up to date according to staleness configuration.

“Up to date” means that either:

• the resource has data (i.e. latestData is not nil),
• the last request succeeded (i.e. latestError is nil), and
• the timestamp on latestData is more recent than expirationTime seconds ago,

…or:

• the last request failed (i.e. latestError is not nil), and
• the timestamp on latestError is more recent than retryTime seconds ago.

Ensures that there is a load request in progress for this resource, unless the resource is already up to date.

If the resource is not up to date and there is no load request already in progress, this method calls load().

Initiates a GET request to update the state of this resource. This method forces a new request even if there is already one in progress. (See loadIfNeeded() for comparison.) This is the method to call if you want to force a check for new data — in response to a manual refresh, for example, or because you know that the data changed on the server.

Sequence of events:

1. This resource’s isLoading property becomes true, and remains true until the request either succeeds or fails. Observers immedately receive ResourceEvent.requested.
2. If the request is cancelled before completion, observers receive ResourceEvent.requestCancelled.
3. If the server returns a success response, that goes in latestData, and latestError becomes nil. Observers receive ResourceEvent.newData.
4. If the server returns a 304, latestData’s timestamp is updated but the entity is otherwise untouched. latestError becomes nil. Observers receive ResourceEvent.notModified.
5. If the request fails for any reason, whether client-, server-, or network-related, observers receive ResourceEvent.error. Note that latestData does not become nil; the last valid response always sticks around until another valid response arrives.

Updates the state of this resource using the result of the given request. Use this method when you want a request to update latestData or latestError and notify observers just as load() would, but:

• you need to use a request method other than GET,
• you need to set headers or other request options, but just for this one request (so that Service.configure(...) won’t work), or
• for some arcane reason, you want a request for a different resource to update the state of this one.

For example, an authentication resource might return its state only in response to a POST:

let auth = MyAPI.authentication
auth.load(using:
  auth.request(
      .post, json: ["user": user, "password": pass]))

If this resource has no observers, cancels all loadRequests.

Convenience to call cancelLoadIfUnobserved() after a delay. Useful for situations such as table view scrolling where views are being rapidly discarded and recreated, and you no longer need the resource, but want to give other views a chance to express interest in it before canceling any requests.

The callback is called after the given delay, regardless of whether the request was cancelled.

Directly updates latestData without touching the network. Clears latestError and broadcasts ResourceEvent.newData to observers.

This method is useful for incremental and optimistic updates.

You may send a request which does not return the complete state of the resource in the response body, but which still changes the state of the resource. You could handle this by initiating a refresh immedately after success:

resource.request(.post, json: ["name": "Fred"])
  .onSuccess { _ in resource.load() }

However, if you already know the resulting state of the resource given a success response, you can avoid the second network call by updating the entity yourself:

resource.request(.post, json: ["name": "Fred"])
  .onSuccess {
      partialEntity in

      // Make a mutable copy of the current content
      guard resource.latestData != nil else {
          resource.load()  // No existing entity to update, so refresh
          return
      }

      // Do the incremental update
      var updatedContent = resource.jsonDict
      updatedContent["name"] = partialEntity.jsonDict["newName"]

      // Make that the resource’s new entity
      resource.overrideLocalContent(with: updatedContent)
  }

Use this technique with caution!

Note that the data you pass does not go through the standard ResponseTransformer chain. You should pass data as if it was already parsed, not in its raw form as the server would return it. For example, in the code above, updatedContent is a Dictionary, not Data containing encoded JSON.

Convenience method to replace the content of latestData without altering the content type or other headers.

If this resource has no content, this method sets the content type to application/binary.

Forces the next call to loadIfNeeded() to trigger a request, even if the current content is fresh. Leaves the current values of latestData and latestError intact (including their timestamps).

Use this if you know the current content is stale, but don’t want to trigger a network request right away.

Any update to latestData or latestError — including a call to overrideLocalData(...) or overrideLocalContent(...) — clears the invalidation.

Resets this resource to its pristine state, as if newly created.

• Sets latestData to nil.
• Sets latestError to nil.
• Cancels all resource requests in progress.
• Triggers a cache fetch if there is a persistent cache configured for this resource.

Observers receive a newData(.wipe) event. Requests in progress call completion hooks with a cancellation error.

Matches this specific resource when passed as a pattern to Service.configure(...).

Typed content accessors such as .text and .jsonDict apply to latestData?.content.

Returns a request that immedately fails, without ever touching the network or applying the transformer pipeline.

This is useful for performing pre-request validation: if you know a request is invalid before you even send it, you can return an immediate error response that looks just like any other Siesta error.

Returns a request that immediately and always returns the given response, without ever touching the network or applying the transformer pipeline.

Creates (but does not start) a new request using custom request logic.

This method allows you to make a request using custom / external logic that does not use the service’s normal network provider. For example, you could use this to wrap a third-party OAUth library as a Siesta request, then use Configuration.decorateRequests(...) and Request.chained(...) to wait for OAuth before proceeding with the normal Siesta request.

Convenience method to initiate a request with a body containing arbitrary data.

Convenience method to initiate a request with a text body.

If the string cannot be encoded using the given encoding, this methods triggers the onFailure(...) request hook immediately, without touching the network.

Convenience method to initiate a request with a JSON body.

If the json cannot be encoded as JSON, e.g. if it is a dictionary with non-JSON-convertible data, this methods triggers the onFailure(...) request hook immediately, without touching the network.

Convenience method to initiate a request with URL-encoded parameters in the meesage body.

This method performs all necessary escaping, and has full Unicode support in both keys and values.

The content type is application/x-www-form-urlencoded.

Returns the resource with the given string appended to the path of this resource’s URL, with a joining slash inserted if necessary.

Use this method for hierarchical resource navigation. The typical use case is constructing a resource URL from path components and IDs:

let resource = service.resource("/widgets")
resource.child("123").child("details")
  //→ /widgets/123/details

This method always returns a subpath of the receiving resource. It does not apply any special interpretation to strings such ./, // or ? that have significance in other URL-related situations. Special characters are escaped when necessary, and otherwise ignored. See ResourcePathsSpec for details.

Returns the resource with the given URL, using this resource’s URL as the base if it is a relative URL.

This method interprets strings such as ., .., and a leading / or // as relative URLs. It resolves its parameter much like an href attribute in an HTML document. Refer to ResourcePathsSpec for details.

Returns relative(href) if href is present, and nil if href is nil.

This convenience method is useful for resolving URLs returned as part of a JSON response body:

let href = resource.jsonDict["owner"] as? String  // href is an optional
if let ownerResource = resource.optionalRelative(href) {
  ...
}

Returns this resource with the given parameter added to or changed in the query string.

If value is an empty string, the parameter appears in the query string with no value (e.g. ?foo).

If value is nil, however, the parameter is removed.

There is no support for parameters with an equal sign but an empty value (e.g. ?foo=). There is also no support for repeated keys in the query string (e.g. ?foo=1&foo=2). If you need to circumvent either of these restrictions, you can create the query string yourself and pass it to relative(_:) instead of using this method. For example:

resource.relative("?foo=1&foo=2")

Returns this resource with all the entries in the given dictionary added to or changed in the query string. Equivalent to chained calls to withParam(_:_:) using each key-value pair in the dictionary.

See withParam(_:_:) for information about the meaning of nil values and empty strings, multi-values params, and canonical parameter ordering.

Adds an self-owned observer to this resource, which will receive notifications of changes to resource state.

The resource holds a weak reference to the observer. If there are no strong references to the observer, it is automatically removed.

Use this method for objects such as UIViewControllers which already have a lifecycle of their own, are retained elsewhere, and also happen to act as observers.

Adds an observer to this resource, holding a strong reference to it as long as owner still exists.

The resource holds only a weak reference to owner, and as soon as the owner goes away, the observer is removed.

The typical use for this method is for glue objects whose only purpose is to act as an observer, and which would not normally be retained by anything else.

Adds a closure observer to this resource.

The resource holds a weak reference to owner, and the closure will receive events only as long as owner still exists.

Removes all observers owned by the given object.