The ORMPOS services often use path parameters rather than query parameters. For example, in this REST URL, the parameters are part of the path:
https://locahost:7002/mpos/services/storeID/registerID/txnID/suspend/reasonCode
In ASA, to construct such a URL, an ATGRestSession
subclass, named ATGPOSRestSession
is used to call ORMPOS URLs without using Oracle Commerce-specific method names.
ATGPOSRestSession
has these methods:
(id <ATGRestOperation>) executeGetRequestForPath:(NSString *) pPath pathParameters: (NSDictionary *) pPathParameters queryParameters: (NSDictionary *) pQueryParameters requestFactory:(id <ATGRestRequestFactory>)pRequestFactory options:(ATGRestRequestOptions) pOptions success:(void ( ^ ) ( id <ATGRestOperation> pOperation , id pResponseObject ))pSuccess failure:(void ( ^ ) ( id <ATGRestOperation> pOperation , NSError *pError ))pFailure;
(void) addSessionPathParameter: (NSString *) pName value: (NSString *) pValue;
These methods differ from others in ATGRestSession
since they implement path parameters. The pathParameters
supplied in an execute*RequestForPath
call are parameters local to that call, whereas the pathParameters
supplied in addSessionPathParameter
are path parameters that do not often change during a session.
This path parameter implementation lets you make this kind of call from a manager method:
self.restManager.restSession executeGetRequestForPath:@"/{storeID}/{registerID}/{txnID}/suspend/{reasonCode}" pathParameters:@{@"reasonCode" : @"123"}, queryParameters:nil requestFactory:nil options:ATGRestRequestOptionNone success:^(id pOperation, id pResponseObject)...
In the previous example, the path is a constant, but you only need to pass the parameter value of the parameter that is specific to this call, in this example, the reason code.
Parameter Management with ATGPOSSessionManager
ATGPOSSessionManager
substitutes any value contained within curly brackets with a pathParameter
of the same name that is either passed in with the execute*RequestForPath
call, or has been passed in to addSessionPathParameter
. If the path string still contains a curly bracket after substitution, a warning is logged. The benefits of this management are:
The path constants are meaningful and readable.
The real values for the path parameters need to be supplied in the correct order during substitution, so are less likely to break if the path ordering changes.
Each manager method does not need to resupply all the common path parameters, such as: API version, store ID, register ID, transaction ID. This makes things less error prone.
Since this is the path format used by ORMPOS, it is easier to compare constants.
Posts
Posts work in exactly the same way as a substitution, for example:
self.restManager.restSession executePostRequestForPath:@"/auth/{version}/login" pathParameters:nil postParameters:@{@"hardwareID" : @"1234"} requestFactory:nil options:ATGRestRequestOptionNone success:^(id pOperation, id pResponseObject)...