Locidoke Simple API

Get API Sample Code
There are many things to consider when creating a web service that will handle your locidoke incoming submissions. The most important is exploitation of the incoming strings. Preferably, all incoming responses should be evaluated from a white list of options. The data coming in will be in multiple parts and each should be examined thoroughly for the expected values. For instance, the first two will be latitude and longitude. These should be evaluated as numeric values. The third should be evaluated as a type of time. The final two values should be evaluated as white listed strings that should only be used if they match a white list "approved" value. Anything other than the white listed values should simply be ignored. If all 5 of the values pass the white list, then and only then should you utilize them. A session key (nunce) is advisable but not currently written into Locidoke at this time. This will prevent man in the middle attacks and avoid submissions being tampered with during transmission of the data. Concept PUSH (Driver) 1. Locidoke connects to the web service and passes the 5 key/value pairs to the service (lat,lon,time,key1,key2). 2. The service evaluates these strings to their expected values. Integer, Integer, Time, White Listed String, White Listed String 3. The service saves the lat,lon,time either to a database or file (using the first white listed (key1) parameter as unique identifier). 4. Key2 white listed parameter is either consumed, or appended to the lat,lon,time data. PULL (Watcher) 1. Locidoke connects to the web service or directly to the file written by the PUSH process. This response should be in the exact same format as the PUSH format which is minimally lat,lon,time. Currently Locidoke is not configured to use the two incoming key values. This could however include something like a message, status, etc on Key2. An example would be "Stopping for lunch" or "My Florida Trip" as a title. 2. Locidoke uses this string to plot the users last location on it's internal map in Watcher Mode. In this coding example, Key1 will be used as the unique identifier of the Locidoke instance making the push. Including something tangible such as the IP address of the incoming client can be useful to make things more unique but you have to be careful of possible proxy addresses. If saw this while testing and found that the IP address of the client was always the same even if run from a different device. It turns out the IP address was the IP of the proxy and not the client. I will not go into how to get around this since it is beyond the scope of this document. PUSH Concept Walkthru (After evaluation to insure all data is cleansed as expected) A string variable called inLoc is created by joining lat,lon,time to a delimited string. 0,0,05/06/2019@10:13:59am 0,0 as lat,lon means that the application could not aquire a location. Possibly location tracking was turned off or it was unable to get lat/lon from GPS on the unit. The inLoc variable is then saved to a text file on the web server. If the file is stored in a location that is available to the web server it can be called directly using the URL path of the file. https://mydomain.com/trips/joesphone.txt. Again, "joesphone" is a white listed value, which means that only "joesphone". This is crutial when saving files because you need to insure there are no "directory walking" characters in the string such as forward slashes, periods or back slashes. Note: Regex can be exploited to cause denial of service attacks, so you need to keep that in mind when evaluating strings and insure you have a regex timeout. You can also use that unique key1 value as your primary key for a database connection if you are going the database route. Simply do an insert or update using that "white listed" key1 value as the unique identifier of the database entry. Be sure to always pass the data as parameters and not embedded in the query string to prevent SQL injections. In the database model, you would simply do (MSSQL) "Update myloctable set [locdata]=@locparam where [uniquekey]=@ukeyparam" PULL Concept Walkthru In the PULL file concept your web service simply opens and returns the "comma delimited location line" within the saved USER.txt file. If this file also includes HTML elements, you will need to remove them or only point to a line that contains the delimited string. A file that only contains the "0,0,05/06/2019@10:13:59am" delimited line is easiest. A file that contains something like (html elements shortened for brevity) <HTML>....<BODY> 0,0,05/06/2019@10:13:59am </BODY></HTML> You could potentially load as array split on \n and only return array element [1] (zero based) from your web service. If using the database model then the PULL call would simply return the value stored for the unique identifier. "SELECT [locdata] from myloctable where [uniquekey]=@ukeyparam" This value would be then output via the web service to the client as a simple delimit string. The Locidoke Watcher will interpret an HTML response and display it as html, but things like links will not be clickable from within the application. This could be useful if you are outputting PUSH data to an html page available on your website instead of a txt file. It will also make it more difficult to extract the actual location string from your page in your PULL service to exclude html elements (see example above). Source Code Walkthru First is to recognize an incoming attempt. If only supporting POST then skip the GET section. Loop through incoming POST key value pairs. As a precaution, you can limit this by doing a count on the key/value pairs. i.e. If count==5 then procede, else stop. Validation: Before saving any variables, be sure to validate them. This can be done using regex or some other method. Lat and Lon should be integers and therefore look up a regex for lat/lon. This will be param [0] param name=lat and [1] param name=lon. Param name=Key 1, parameter index [2] name=time should be time, so do a date/time validation. The third key parameter index [3] (default key1) will be the user authentication identifier. Append a user and password or code together and then parse it on the API side like myusername+delimiter+myauthenticationkey. i.e. key1=username_a8D7x677gGGv7v7VlmzprxZm0004xrRS...(get the picture). This will be the one you want to thoroughly inspect. The preferred method is a white list. This means that unless it exactly matches something already in the list, you disregard everything. It will also be part of the file name or DB entry so cleanse it well. White list keys will insure only what you are expecting is used in the file name. Split that string on the delimiter, using index[0] as the user and index[1] as the authkey. This will allow you to authentication but still use the username for the file name you will need to pass on for checking status. The white list can include the entire string so that you do not need to validate both indexes. You can also do delimiters for the other key, but I am keeping a specific single value and only for the auth key. The last and final key in this 5 parameter index[4] (default key2) service is status. Again, only allowing white list items is the preferred method, though I have made locidoke able to use any value in case someone needs special chars to do splits, arrays, etc. to make it more flexible. V7 and above also contains a select list which is built by a comma delimited string, changeable in the configuration. Selecting an item from the list will store the value as Key2's value. The default string is "Driving, Stopped, Eating, Emergency, Help!". Quick Status list is visible in the main map screen if you turn it on in the configuration. Once you have all the parameters thoroughly cleansed then you have your values to write to a text file or save to a DB table. Do not write key1 contents within the file since this is used for authentication to the API. Another thing to consider is an API threshold which overrides the locidoke timer. Sneaky, I know but this will allow me to charge for the API per post limit. The amount of submissions allowed will change based on the fee. i.e.$20/month every minute, $15/month posts every 5 minutes, $10/month, posts every 10 minutes... Free=1 post per hour, etc. You will still take an API hit from the post, but the API will not do anything except display the last location posted which may be up to an hour old. The way this works is checking the file stamp of the written file (or datestamp in a DB). If the current time is greater than the last post time +X minutes then allow a new post, else display the old post. I also have the option to possibly add advertising in the API for the free version but not in the pay versions. Example API (PHP) Source Code:
Warning: Please note that any source code available on 247Coding.com is to be determined as "Use at your own risk". It should be thoroughly reviewed and tested in your own non-production environment before ever placing into a production environment! By using any source code or software on 247coding.com, you are releasing 247Coding.com and any of it's affiliates from any risk, damage, hardship or otherwise any situation that comes from it's use. Source code on 247Coding.com is being promoted purely as "As IS" and "Use at your own risk".
Get Sample Code