PLYEndpoint.h

Includes:
<Foundation/Foundation.h>

Introduction

Use the links in the table of contents to the left to access the documentation.


Protocols

GenomeMappableRawType
PLYParameterEncodableType

Methods

+deleteWithCompletion:
+endpoint
+endpointWithParameters:
+endpointWithSlug:
+endpointWithSlug:andParameters:
+getWithCompletion:
+initWithParameters:
+initWithSlug:
+initWithSlug:andParameters:
+patchWithCompletion:
+postWithCompletion:
+putWithCompletion:
+transformResponseToMappableRawType:
+valueForSlugPath:withSlug:
+valueIsValid:forSlugPath:

deleteWithCompletion:

- (void)deleteWithCompletion:(void(^)(id object, NSError *error))completion;
Parameters
completion

the return from the completion. Override the variable names in the completion block to suit the method to your needs, for example:

See

getWithCompletion:

endpoint

+ (instancetype)endpoint;
Return Value

A new instance of the endpoint

Discussion

Initializes a new endpoint with an empty slug and an empty query parameters

endpointWithParameters:

+ (instancetype)endpointWithParameters:(id<PLYParameterEncodableType>)parameters;
Parameters
parameters

a PLYParameterEncodableType containing the parameters to send with the request

Return Value

a fully initialized endpoint

Discussion

Initializes the endpoint with the given query parameters to populate the request

endpointWithSlug:

+ (instancetype)endpointWithSlug:(id)slug;
Parameters
slug

an object or a dictionary w/ values that directly correspond to the declared slugpaths within the endpoint

Return Value

a fully initialized endpoint

Discussion

Initializes the endpoint with the given slug that should be used to populate the endpoint

endpointWithSlug:andParameters:

+ (instancetype)endpointWithSlug:(id)slug andParameters:(id<PLYParameterEncodableType>)parameters;
Parameters
slug

an object or a dictionary w/ values that directly correspond to the declared slugpaths within the endpoint

parameters

a PLYParameterEncodableType containing the parameters to send with the request

Return Value

a fully initialized endpoint

Discussion

Initializes the endpoint with the given slug and query parameters

getWithCompletion:

- (void)getWithCompletion:(void(^)(id object, NSError *error))completion;
Parameters
completion

the return from the completion. Override the variable names in the completion block to suit the method to your needs, for example: * @code [ep getWithCompletion:(void(^)(MyModel *model, NSError *error) { // Handle response here. }]; // or [ep getWithCompletion:(void(^)(NSArray *models, NSError *error) { // Handle response here. }];

Discussion

* Network method to perform a get request for a given endpoint * *

initWithParameters:

- (instancetype)initWithParameters:(id<PLYParameterEncodableType>)parameters;
Parameters
parameters

a PLYParameterEncodableType containing the parameters to send with the request

Return Value

a fully initialized endpoint

Discussion

Initializes the endpoint with the given query parameters to populate the request

initWithSlug:

- (instancetype)initWithSlug:(id)slug;
Parameters
slug

an object or a dictionary w/ values that directly correspond to the declared slugpaths within the endpoint

Return Value

a fully initialized endpoint

Discussion

Initializes the endpoint with the given slug that should be used to populate the endpoint

initWithSlug:andParameters:

- (instancetype)initWithSlug:(id)slug andParameters:(id<PLYParameterEncodableType>)parameters NS_DESIGNATED_INITIALIZER;
Parameters
slug

an object or a dictionary w/ values that directly correspond to the declared slugpaths within the endpoint

parameters

a PLYParameterEncodableType containing the parameters to send with the request

Return Value

a fully initialized endpoint

Discussion

Initializes the endpoint with the given slug and query parameters

patchWithCompletion:

- (void)patchWithCompletion:(void(^)(id object, NSError *error))completion;
Parameters
completion

the return from the completion. Override the variable names in the completion block to suit the method to your needs, for example:

See

getWithCompletion:

postWithCompletion:

- (void)postWithCompletion:(void(^)(id object, NSError *error))completion;
Parameters
completion

the return from the completion. Override the variable names in the completion block to suit the method to your needs, for example:

See

getWithCompletion:

putWithCompletion:

- (void)putWithCompletion:(void(^)(id object, NSError *error))completion;
Parameters
completion

the return from the completion. Override the variable names in the completion block to suit the method to your needs, for example:

See

getWithCompletion:

transformResponseToMappableRawType:

- (id<GenomeMappableRawType>)
        transformResponseToMappableRawType:(id)response;
Parameters
response

the response to map

Return Value

the value received from the response

Discussion

When a response is received from an api, you can use this method to provide customized behavior. A common use ase for this is when using an XML api that can not be automatically converted to a dictionary. You can use this to transform the data to a mappable type. You can also implement customized functionality as necessary for specialized circumstances.

valueForSlugPath:withSlug:

- (id)valueForSlugPath:(NSString *)slugPath withSlug:(id)slug;
Parameters
slugPath

the slug path that is being populated

slug

the slug that is being used to populate the endpoint's slug paths

Return Value

the value to insert into the url, or nil if the slugpath should be removed from the url

Discussion

When populating the endpoint with a given slug, by default, the endpoint will call: `[slug valueForKeyPath:slugPath];`. You can use this to override that behavior and provide custom functionality that allows for multiple slug types to be used.

valueIsValid:forSlugPath:

- (BOOL)valueIsValid:(id)value forSlugPath:(NSString *)slugPath;
Parameters
value

the value that will be injected into the url

slugPath

the path that will be replaced

Return Value

whether or not to inject this value into the url at the given slug path, if NO, the path is not appended

Discussion

Use this to prevent a value from being set to a slug, for example an NSInteger identifier might be invalid if it has a value of 0, or less than one and shouldn't be appended to the url.

Properties

acceptableContentTypes
baseUrl
endpointUrl
headerFields
requestSerializer
responseKeyPath
responseSerializer
returnClass
shouldAppendHeaderToResponse

acceptableContentTypes

@property (nonatomic,
    readonly) NSSet *acceptableContentTypes;
Discussion

The content types that can be accepted

baseUrl

@property (nonatomic,
    readonly,
    copy) NSString *baseUrl;
Discussion

Use this to configure the base Url. An ideal architecture only overrides this in one base class and then each endpoint subclasses from there

endpointUrl

@property (nonatomic,
    readonly,
    copy) NSString *endpointUrl;
Discussion

The endpoint url that will be appended to the end of the base url, or a complete URL Example: @"/repos/:owner/:name/issues/:identifier"

headerFields

@property (nonatomic,
    readonly) NSDictionary *headerFields;
Discussion

The header fields to be added to the request

requestSerializer

@property (nonatomic,
    readonly) AFHTTPRequestSerializer<AFURLRequestSerialization> *requestSerializer;
Discussion

A custom request serializer

responseKeyPath

@property (nonatomic,
    readonly,
    copy) NSString *responseKeyPath;
Discussion

The key to use when parsing a JSON response.

responseSerializer

@property (nonatomic,
    readonly) AFHTTPResponseSerializer<AFURLResponseSerialization> *responseSerializer;
Discussion

A custom response serializer

returnClass

@property (nonatomic,
    readonly) Class returnClass;
Discussion

The type of class that is returned from this endpoint.

WARNING:

Must conform to protocol JSONMappableObject

shouldAppendHeaderToResponse

@property (nonatomic,
    readonly) BOOL shouldAppendHeaderToResponse;
Discussion

* In some cases, a header includes values that need to be appended to the model. For these situations, the header can be appended to the JSON mapping dictionary. If the response is a dictionary, an additional field will be added called 'Header', and values can be accessed via keypath syntax, ie: Header.etag. * * If the response is an array, it will be appended to the key "response" for mapping. * * The use case is when the header has values you want parsed into your model. For example a results page where the next, previous, and last page are included in the header. In these situations, you can use the keypath Header.Link, etc. in your mapping to map from the header. * * Use Header.headerValue when accessing header values in your object mapping * * Headers will be appended in the following format * @code // Array Responses @{ @"Header" : @{ @"headerKey" : @"headerVal" }, @"response" : @[] // array response }

// Dictionary Responses @{ @"Header" : @{ @"headerKey" : @"headerVal" }, // The rest of the response appears here w/ top level keys as normal }

 

Last Updated: Sunday, April 19, 2015