How to appropiately expose parameters in native library for REST API? - objective-c

Question

I need to write a native Objective-C library to expose REST API resources but I'm having a hard time deciding what is the most appropriate way of exposing the resource's parameters when such parameters are many.
The goal of this library is that it must be easy to use.
So, say that I have a resource: GET /users, it returns a list of Users and I can set parameters in the request to limit the number of results, to filter by name, role, and other criteria. There are many optional parameters that can be set in the request and I have to expose them all in this library.
So far I have three ideas on how to do this:
(the pros/cons are the ones I can see now, doesn't mean there aren't more)
Option A: Create ResourceRequest class for each resource
Define for example a class UsersRequest for accessing the Users resource:
#interface UsersRequest
// Default value: 500 users
#property (nonatomic) int limit;
// The starting point in the ordered list of results
#property (nonatomic) int offset;
// if set, the response will contain only users whose
// id's are in the array. This will override any other parameter.
#property (nonatomic, retain) NSArray* userIDs;
// if set to YES, will filter out users that have been read
#property (nonatomic) BOOL unread;
// defines the users types to filter from the results
#property (nonatomic, retain) NSArray* types;
// if set, it will filter out users not containing the text.
#property (nonatomic, copy) NSString* text;
#end
Then I would be able to access the resource with something like:
UsersRequest* request= [[UsersRequest alloc] init];
request.limit= 100;
request.text= #"test";
request.userIDs= #[#1,#2,#3];
[requestManager sendAsynchronous:request success:^(id response) {
NSLog(#"Success! %#", response);
} failure:^(NSError *error) {
NSLog(#"Error: %#", error);
}];
Pros
I like that I only have to create a single method to send the request.
I like that if two or more resources share the same parameter, I can create a hierarchy of ResourceRequest classes and add the specific parameters to specific classes, e.g., say that resource A and B need the limit parameter, then I can define limit as a property of the base class ResourceRequest of ARequest and BRequest
I can use auto-complete to seach for the options I need.
Cons
I have to create one class per resource.
Option B: Pass the parameters as a NSDictionary using constant strings as keys
This implies defining constant strings somewhere:
NSString* const Limit= #"limit";
NSString* const Offset= #"offset";
NSString* const UserIDs= #"UserIDs";
And then calling something like:
NSDictionary* parameters= #{Limit: #50,
Offset: #10,
UserIDs:#[#1, #2, #3]};
[requestManager getUsersWithParams:parameters
success:^(NSArray* usersFound){
NSLog(#"Success! %#", usersFound);
}
failure:^(NSError* error){
NSLog(#"Error: %#", error);
}];
Cons
I have to create one method per resource.
The developer must know the names of the keys for each parameter. He cannot use autocomplete to quickly search for the one he needs.
Option C: Create an RequestParams class and pass that
Define the RequestParams class like:
#interface RequestParams : NSObject
#property (nonatomic) int limit;
#property (nonatomic) int offset;
#property (nonatomic, retain) NSArray* messagesIDs;
#end
And the use as follows:
RequestParams* parameters= [[RequestParams alloc]init];
parameters.limit= 100;
parameters.offset= 20;
parameters.userIDs= #[#1, #2, #3];
[requestManager getUsersWithParams:parameters
success:^(NSArray* usersFound){
NSLog(#"Success! %#", usersFound);
}
failure:^(NSError* error){
NSLog(#"Error: %#", error);
}];
Cons
One method per resource.
Pros
I can use auto-complete to search for the options I need.
I can also create a hieraychy of options classes to refine the options for different resources.
What would be a good way of exposing the resource's parameters? I want to avoid writing methods with 10+ parameters.

Answer 1

Option B doesn't make sense since it has a lack of easiness to use and if you're planning to have a well defined api in order to scale its functionality you will end with tens of constants in your header file.
So is most likely to have option A, you can even have a RequestDelegate
and have some methods maybe for observing the request progress something like
-(void)requestWillPrepareForSend(Request *)request;
or something like
-(void)request:(Request *)request didLoadResponse:(Response *)response;
for handling successful request.
I am not pretty sure what frameworks or libraries are you using to help you handling this scenarios but there should be something out there like AFNetworking that may be is already handled.
Where I'm actually working we have the option C approach and it's a really pain in the ass when you want to unit test a class with tens of methods, so that even though it could be a disadvantage to have a class per resource if you are thinking tdd I recommend to have small chunks of code for unit testing.

Answer 2

If the goal is release an easy to use API, automatically the option B is discarded, due to it doesn't permit autocomplete.
Then I think you must use de option A, with it you can easy organize all parameters per resource and in my experience is much better for code maintenance. The wsdl2java plugin (create class for SOAP comunication) works something like that, a class per resource.

Answer 3

Well, let's see... due to autocomplete issue option B it's no a good idea, will force developers to consult some API documentation every time they write a new request just for know how to write the parameters... option A and option C are both pretty similar but option C makes you write one request per resource in your RequestManager class mixing all the requests, so that option A seems better option to me, one class per resource that handles it's own request (parsing the response and so on), more mainteinable.