Objective C API wrapper

From translatewiki.net
Jump to: navigation, search

General description

This page describes the project: objc-twapi

This project is a library, intended for handling the translatewiki.net API in Objective C. It encapsulates all the HTTP communication that is executed on every API request.

For using it, one should create a object of type TWapi, that stores the information about the current user that makes requests to the API. The requests are done through this object. One should create it with a TWUser object, describing the user that is logged in to the systems and makes requests to the API.

It handles the requests asynchronously, with a few synchronous functions.

Functions

Here is the documentation about the various functions in TWapi.h:

Documentation
Function Description
-(id) initForUser:(TWUser*) linkedUser; Initialization of the TWapi object, with a user object.
-(void)TWPerformRequestWithParams:(NSDictionary *)params completionHandler:(void (^)(NSDictionary *, NSError *))completionBlock; Asynchronous general request - this is the sole method which "speaks" to the API server.

It does:
a) Prepares an HTTP request out of the given parameters;
b) Creates a connection with the API server, send the request and receive its response;
c) Handles response: invokes handler, inform on error, parse JSON, and send it to the given completionBlock completionBlock is a pointer to the block of code that will be executed when the response will return. It will get a dictionary of the JSON results, and the error. The function also gets a dictionary of the POST data parameters, with mappings between key and value.

-(void)TWLoginRequestWithPassword:(NSString*) passw completionHandler:(void (^)(NSString *, NSError *))completionBlock; Login Request - this method handles login request by two steps:

1) Requests token
2) Uses token for login approval
Parameters: passw is the password as string (remember: the user name is in TWUser object stored in TWapi object), completionBlock (see TWPerformRequestWithParams)

-(void)TWLoginRequestWithPassword:(NSString*) passw isMainThreadBlocked:(BOOL)isBlocked completionHandler:(void (^)(NSString *, NSError *))completionBlock; isMainThreadBlocked=YES means that the main thread is blocked (for example by a loop that makes the thread sleep until the response arrives), because it has to know the response before it can continue
-(void)TWLogoutRequest:(void (^)(NSDictionary *, NSError *))completionBlock; Logout request. Parameter: completionBlock (see TWPerformRequestWithParams)
-(void)TWEditRequestWithTitle:(NSString*)title andText:(NSString*)text completionHandler:(void (^)(NSError *, NSDictionary*))completionBlock; Request to edit some page, with the title title, and requesting the text of the page to be text. completionBlock: see TWPerformRequestWithParams.
-(void)TWTranslatedMessagesListRequestForLanguage:(NSString*)lang Project:(NSString*)proj Limitfor:(NSInteger)limit OffsetToStart:(NSInteger)offset completionHandler:(void (^)(NSDictionary *, NSError *))completionBlock; Request to get a list of translated messages for the language lang, for the project proj, with the limit of up to limit messages, and an offset of offset. completionBlock: see TWPerformRequestWithParams.
-(void)TWUntranslatedMessagesListRequestForLanguage:(NSString*)lang Project:(NSString*)proj Limitfor:(NSInteger)limit OffsetToStart:(NSInteger)offset completionHandler:(void (^)(NSDictionary *, NSError *))completionBlock; Request to get a list of untranslated (!fuzzy|!translated) messages for the language lang, for the project proj, with the limit of up to limit messages, and an offset of offset. completionBlock: see TWPerformRequestWithParams.
-(void)TWTranslationAidsForTitle:(NSString*)title withProject:(NSString*)proj completionHandler:(void (^)(NSDictionary *, NSError *))completionBlock; Request to get the dictionary of translation aids, for the page with the title title, under the project proj. This dictionary includes translation suggestions and documentation. completionBlock: see TWPerformRequestWithParams.
-(void)TWTranslationReviewRequest:(NSString *)revision completionHandler:(void (^)(NSError *, NSDictionary*))completionBlock; Request to accept (translation review) an existing translation, which has the revision revision (a number, stored as string). completionBlock: see TWPerformRequestWithParams.
-(void)TWProjectListMaxDepth:(NSInteger)depth completionHandler:(void (^)(NSArray *, NSError *))completionBlock; Request to get a list of the translatewiki.net's projects up to some depth depth. completionBlock: see TWPerformRequestWithParams.
-(void)TWQueryRequestAsync:(NSDictionary *)params completionHandler:(void (^)(NSDictionary *, NSError *))completionBlock; General request of action=query. completionBlock: see TWPerformRequestWithParams.
-(NSString*)TWUserIdRequestOfUserName:(NSString*)userName; Request to get the user id of some user name userName.
-(NSMutableDictionary *)TWRequest:(NSDictionary *)params; Synchronous version of TWPerformRequestWithParams.
-(NSMutableDictionary *)TWQueryRequest:(NSDictionary *)params; Synchronous version of TWQueryRequestAsync.
-(NSDictionary *)TWEditRequest:(NSDictionary *)params; Synchronous edit request.

Properties

Description of the TWapi properties:

Documentation
Property Description
@property(nonatomic, copy)TWUser* user; The user object that contains the information about the user making requests to api
@property(nonatomic) dispatch_queue_t queue; The queue in which the api requests are being made

Description of the TWUser properties:

Documentation
Property Description
@property(nonatomic, copy)NSString* userName; User name
@property(nonatomic, copy)NSString* userId; User id
@property BOOL isLoggedin; Did the authentication succeed, and the user is logged in