Inherits from NSObject
Declared in RKRouter.h

Overview

An RKRouter instance is responsible for generating NSURL objects with a given base URL and a route set. It is used to centralize the knowledge about the URL’s that are used by the application.

Route Generation

URL’s can be generated by the router in three ways:

  1. By name. Named routes link a symbolic name with a path and an HTTP request method. (see URLForRouteNamed:method:object:)
  2. By object. Routes can be defined by class and HTTP request method. When a URL is requested from the router for an object, the router will identify the most appropriate route for the object and instantiate an NSURL with the route’s path pattern and interpolate it against the object. (see URLForObject:method:)
  3. By object relationship. Routes can be defined for relationships to other objects. When a URL is requested from the router for a relationship, the router will retrieve the appropriate route for the relationship from the route set and interpolate the route’s path pattern against the source object. (see URLForRelationship:ofObject:method:)

Tasks

Initializing a Router

Generating URLs

Configuring the Base URL and Route Set

  •   baseURL

    The base URL that all URLs constructed by the receiver are relative to.

         property
  •   routeSet

    A route set defining all the routes addressable through the receiver.

         property

Properties

baseURL

The base URL that all URLs constructed by the receiver are relative to.

@property (nonatomic, strong, readwrite) NSURL *baseURL

Declared In

RKRouter.h

routeSet

A route set defining all the routes addressable through the receiver.

@property (nonatomic, strong, readonly) RKRouteSet *routeSet

Declared In

RKRouter.h

Instance Methods

URLForObject:method:

Generates a URL for a given object and HTTP method.

- (NSURL *)URLForObject:(id)object method:(RKRequestMethod)method

Parameters

object

The object for which a URL is to be generated.

method

The HTTP method for which the URL is to be generated.

Return Value

A new URL object constructed by appending the path pattern of the route for the object an HTTP method to the baseURL of the receiver, interpolated against the routed object; or nil if no route was found for the given object and HTTP method.

Discussion

The route set is searched for a route that matches the HTTP method and class of the object being routed. If there is not an exact match for the object’s class, the inheritance hierarchy is searched until a match is found or all possible routes are exhausted. Exact HTTP request matches are favored over the wildcard method (RKRequestMethodAny). Once the appropriate route is identified, a new NSURL object is instantiated with the baseURL of the receiver and the path pattern of the route, interpolated against the object being routed.

Declared In

RKRouter.h

URLForRelationship:ofObject:method:

Generates a URL for a relationship of a given object with a given HTTP method.

- (NSURL *)URLForRelationship:(NSString *)relationshipName ofObject:(id)object method:(RKRequestMethod)method

Parameters

relationshipName

The name of the relationship for which a URL is to be generated.

object

The object for which the URL is to be generated.

method

The HTTP method for which the URL is to be generated.

Return Value

A new URL object constructed by appending the path pattern of the route for the given object’s relationship and HTTP method to the baseURL of the receiver, interpolated against the routed object; or nil if no route was found for the given relationship, object and HTTP method.

Discussion

The route set is searched for a route that matches the relationship of the given object’s class and the given HTTP method. If a matching route is found, a new NSURL object is instantiated with the baseURL of the receiver and the path pattern of the route, interpolated against the object being routed.

Declared In

RKRouter.h

URLForRouteNamed:method:object:

Generates a URL for the route with the given name.

- (NSURL *)URLForRouteNamed:(NSString *)routeName method:(out RKRequestMethod *)method object:(id)object

Parameters

routeName

The name of the route for which a URL is to be generated.

method

A pointer to an RKRequestMethod variable in which to store the HTTP method associated with the named route. May be nil.

object

An optional object against which to interpolate the path pattern.

Return Value

A new NSURL object constructed by appending the path pattern to the baseURL of the receiver and interpolating against a given object; or nil if no route was found with the given name.

Discussion

The route set is searched for a route with the given name and a new NSURL object is instantiated with the baseURL of the receiver and the path pattern of the route, optionally interpolated with a given object. If a pointer to an RKRequestMethod variable is provided, the HTTP method for the route will be assigned to the reference.

Declared In

RKRouter.h

URLWithRoute:object:

Generates a URL with a given route and object.

- (NSURL *)URLWithRoute:(RKRoute *)route object:(id)object

Parameters

route

The route to generate the URL with.

object

The object with which to interpolate the path pattern of the given route.

Return Value

A new URL object constructed by interpolating the path pattern of the given route with the given object to construct a path and constructing an NSURL object relative to the baseURL of the receiver.

Declared In

RKRouter.h

initWithBaseURL:

Initializes a router with a given base URL.

- (id)initWithBaseURL:(NSURL *)baseURL

Parameters

baseURL

The base URL with which to initialize the receiver.

Return Value

The receiver, initialized with the given base URL.

Declared In

RKRouter.h