Data Web Service - Client Guide

Transcription

1 Data Web Service - Client Guide Introduction The Redcat Data Web Service is a standard, secure way for approved Redcat clients to retrieve data ir SmartReports database. Update access is also available for some table datasets. Query datasets are not updatable. The data is accessed via a RESTful API. Response Formats Supported data formats are: HTML XML JSON Request Format The format of a request follows a defined pattern: «client».redcat.com.au/smartreports/data/api/«dataset»/[«field»][«filter»][.«format»]?«opti ons» Where: «client» is the client slug. For example, robbos, robbostest «dataset» is the name of the table or query (see "Datasets" below) «format» is either "html", "xml", or "json". Optional. Default is "html" «field» this is a field name within the dataset and means that only this field (column) of data will be returned. For example, The BalanceDate field on the -monthly dataset is /-monthly/balancedate. «filter» filter to reduce the data returned. The filter is dependant on the field type. For example, the filter for -monthly records where the BalanceDate is in year 2009 is /-monthly/balancedate/2009 «options» are a combination of further options to control how data is to be extracted. The available options are: limit - his is the maximum number of records to return. Must be 1000 or less. Default is For example, limit =400 offset - his is the starting record offset (the first record is at offset 0) from which to extract records. Default is 0. For example, offset=1999 (this will start 2000th record) order - one or more field-names, separated by " ", defining the order of the records. Examples: - sort by "id" descending: order=~id - sort by BalanceDate then TotalRedeemedMoney descending: order=balancedate ~TotalRedeemedMoney NOTES 1. The allowed «filter» is dependant on the dataset. The format described above is a generic syntax for a request. A special request that returns all the possible patterns (for tables only) is /smartreports/data/api/patterns.xml 2. Queries are restricted to the following «filter» patterns: a. /«field»/«value» The service will returns only rows where the «field» value equals «value» b. /«field»/«value1»/«value2» The service will returns only rows where the «field» value is between «value1» and «value2» Request Examples -monthly Description URL (the domain is not displayed for brevity)

2 The first 1000 rows dataset Only the TotalRedeemedMoney column of the first 1000 rows dataset 100 rows 1000th row dataset The first 1000 rows dataset sorted by id ascending The first 1000 rows dataset sorted by id descending The first 1000 rows dataset sorted by BalanceDate then TotalRedeemedMoney The row with id Only the TotalRedeemedMoney column of the row with id Rows that have a MemberID between 50 and 100 inclusive Rows where the last transaction date was between 1/1/2015 and 1/3/2015 All the possible request patterns Latest data from tbl_saleheader since ' :00:00' The next latest data after the above /smartreports/data/api/-monthly.xml /smartreports/data/api/-monthly/totalredeemedmoney.xml /smartreports/data/api/-monthly.xml/?limit=100&offset=999 /smartreports/data/api/-monthly.xml/?order=id /smartreports/data/api/-monthly.xml/?order=~id /smartreports/data/api/-monthly.xml/?order=balancedate TotalRedeemedMoney /smartreports/data/api/-monthly/id/37616.xml /smartreports/data/api/-monthly/id/37616/datetimestamp.xml /smartreports/data/api/-monthly/memberid/50/100 /smartreports/data/api/-monthly/datetimestamp/ / xml /smartreports/data/api/patterns.xml /smartreports/data/api/tbl-saleheader/txndate/ %2012:00:00.json/?limit=10&offset /smartreports/data/api/tbl-saleheader/txndate/ %2012:00:00.json/?limit=10&offset Security and Restrictions The service is tightly secured, due to the potentially sensitive client data being exposed to the Internet.

3 The service uses public and private keys, along with a timestamp, to protect the request from client to server. Each request must be signed by combining the keys and timestamp, and then encoding with the secure SHA256 hashing algorithm. The signature is checked by the server and denied if it is not valid. If a request is denied then the HTTP code 403 "FORBIDDEN" is returned, with no data. Also, the data content of the request and response are SSL-encrypted because the service is available only via https. Public API key This key given to the client and may be known by the public. It is only one part of the security rules. This public key is f95ccec0409e4376b64cf4b ce Private API key This key given to the client and must be kept private. It will never be transmitted over the Internet. Each client will have their own key and will declared by Redcat in the client config file as clientapikey in the GlobalOptions section. Timestamp Check When the client makes a request they must also request a date Redcat server. This date is used to check (1) that the client is not making too many repeated requests and (2) that the request is not too old. Both these scenarios are considered unusual enough to be denied. Record Limit To control the size of requests, the server will never return more than 1000 records. If the client expects more than 1000 records in a dataset then they will use the limit and offset parameters and a loop until there are no more records returned. If the client attempts to request more than 1000 records, then the request will be denied. Extracting Data You will need to write a program, in your preferred language, to extract the data. The program will satisfy the authorisation requirements, make the request, retrieve the response, and extract the data. This documentation will assume Python as the chosen language. The language does not matter; the process does. Process 1. Get the public key from Redcat. Declare it as follows: REDCAT_PUBLIC_KEY = f95ccec0409e4376b64cf4b ce 2. Get your client (private) key from Redcat. Declare it as follows: REDCAT_CLIENT_KEY = 95bb084dc0e545d78fb5b8e084bca Retrieve the Redcat Date response = urllib2.urlopen(' headers = response.info() redcat_date = headers['x-redcat-date'] 4. Prepare the authorisation by hashing the private key and Redcat Date with the SHA256 hashing algorithm. Then prepend the public key, as follows:

4 hm = hmac.new(redcat_client_key, redcat_date, hashlib.sha256) sig = base64.b64encode(hm.digest()).decode('utf-8') redcat_auth = ','.join([redcat_public_key, sig]) 5. Make the request to retrieve data by passing the headers: X-Redcat-Authorization, X-Redcat-date, User-Agent and submitting an HTTP GET request. This request is for the first 20 records in JSON format: url = " 0" headers={"x-redcat-authorization" : redcat_auth, "X-Redcat-date" : redcat_date, "User-Agent": "Redcat Web Service Test Client"} request = urllib2.request(url, headers) response = urllib2.urlopen(request) 6. Convert the string JSON response into a dictionary and display the data response_dict = json.loads(response.read()) # The response is returned as a list of records in the 'content' object count = len(response_dict['content']) if count > 0: for item in response_dict['content']: print 'MemberId=%s, TotalRedeemed=%s' % (item['memberid'], item['totalredeemed']) 7. Updating data requires a similar approach except we submit an HTTP PUT request. This request will update the GivenNames for member number : data = {"GivenNames": "Derek Allan Jones"} url = " headers = {"X-Redcat-Authorization" : redcat_auth, "X-Redcat-date" : redcat_date, "User-Agent": "Redcat Web Service Test Client"} request = requests.put(url, data=data, headers={"x-redcat-authorization" : redcat_auth, "X-Redcat-date" : redcat_date, "User-Agent": "Redcat Web Service Test Client"}) print request.status_code Available Datasets Tables Table Name tbl-card-adjustment tbl-card-balance tbl-card-range tbl-card-raw-txn -monthly -store-daily tbl-clerk tbl-coupon-program tbl-department tbl-ecr-hrs tbl-employee Updatable Fields

5 tbl-location tbl-location-mix tbl-member GivenNames tbl-member-coupon tbl-plu tbl-plu-category tbl-plu-class tbl-pos-exception-log tbl-pos-media-log tbl-prodmon-times tbl-product-mix tbl-product-summary-daily tbl-product-summary-half-hourly tbl-product-summary-service tbl-reporting-category tbl-saleheader tbl-saleline tbl-salesrecord-txn tbl-state Queries Query Name qry-grilld-time-attendance-export qry-grilld-payroll-daily-export qry-impact-data qry-points-balance qry-member-program qry-member-purchase qry-redemption-date qry-member-monthly-balance qry-real-time-sales qry-member-updates qry-saleline qry-sales-summary-detailed POST functions Route Body input Description

6 coupon/display/coupon_program_id {"MemberIDs": [1,2,3,4,"7",8,9]} Displays the coupon details (COUPON_PROGRAM_ID) for a list of members