#Licklist API Reference v2# *Created: 17th Dec 2013* Please use: http://epiceditor.com/ to create html The api is used to build third party clients to licklist.co.uk. The api should be used for Mobile native apps. ### Secondary requests ### The secondary request is request which request some data from the server or post some data from the user's behaviour. Secondary request could be user lick something, or user comment something and so on. The actions usually require user to be authenticated infront of the server. To Authenticate the user again the client need to pass custom header which will carry authentication parameters Header: X-Licklist - Pass custom headers with name "X-Licklist". The header itself should contain json string with the following format: {"userid":"[USER-ID]","hash":"[USER-HASH]"} userid and hash can be taken from the login response: * userid: data.user.id (or data.hash.user_id) * hash: data.hash.hash ### API Extensions ### When requesting api the client can choose between 2 extensions: * .json - return data as json string. Could be used in mobile native development as it return the all necessary data * .hson - return data as json string, but leaves of that json will contain preformated html (html json). It's useful when you need to request data and append it to a list or directly into the dom Example is search results which could return nodes as html ready to be assigned to the list *When there is no extension, the response will be the standart desktop content* ### Objects ### Each data should have object node which identify what type is the data returned. For example if you use Search call the data will contain different nodes of data, such as User, Venue, Event, Offer etc. Every node will have attribute `object` which will identify what is it. object should be singular with first capital leter. If the object is combination of 2 words then the second word will be also camel case. Ex: GoingOut. All sub nodes which are objects will be labeled with capital leter, See "Photos / Images" below for reference ### Attributes ### #### Attribute legacy #### Because of legacy, some api calls will contain duplicated attributes. For example if you make user call you will notice that there are attributes which carry the same information like: id = users_id or first_name = users_fname Please use the more "semantic ones" like id, user_id, first_name, last_name, town_id etc. instead of users_id, users_fname, users_sname, users_town, etc. Since on a later stage they will be removed #### Photos / Images #### Each entry which has image assigned will have sub node "Photo" containing "object", "id", "url", "width", "height", "ratio" If this node is missing, meaning that the entry doesn't have image and default should be used (if required). Example of Photo response: "Photo": { "object": "Upload", "id": "2600334", "url": "https://licklist.co.uk/photo/2600334.jpg", "width": "403", "height": "403", "ratio": 1 } *Please, don't construct the url, but use the url provided, since on later stage the urls will be provided from CDN server* # Available calls # Login ------------------------------ URL: https://licklist.co.uk/login.json Header: X-Licklist Pass custom headers with name "X-Licklist" the header itself should contain json string with the following format: {"email":"[USER-EMAIL]","password":"[USER-PASSWORD]"} Parameters: $_POST["data[UsersDevice][type]"] - optional, string could be either ios or android for now. It come together with the next one $_POST["data[UsersDevice][uid]"] - optional, string device uid Response: json string you need to check success if it's true if the login is successfill You need to keep data.hash node since later on it will be used to authenticate the user for the further calls Note: If the fields data[UsersDevice][type] and data[UsersDevice][uid] are provided the device will be activated, so the notifications could be sent to the user Logout ------------------------------ URL: https://licklist.co.uk/logout.json Header: none Parameters: $_POST["data[UsersDevice][type]"] - optional, string could be either ios or android for now. It come together with the next one $_POST["data[UsersDevice][uid]"] - optional, string device uid Response: json string Note: If the fields data[UsersDevice][type] and data[UsersDevice][uid] are provided the device will be deactivated and it won't receive push notifications Register ------------------------------ URL: https://licklist.co.uk/register.json Header: none Parameters: data need to be passed with the following notation: data[User][field] = [VALUE] Example: data[User][first_name] = "John" All Parameters which need to be passed are (all parameters should be passed as $_POST): * data[User][first_name] - required, string * data[User][last_name] - required, string * data[User][email] - required, string * data[User][password] - required, string * data[User][phone] - required, 11+ digits, no space no dash * data[User][birthday] - required, could be date in the following format YYYY-mm-dd or data[User][birthday][] - first element - day data[User][birthday][] - second element - month data[User][birthday][] - third element - year From the array should be able to be created date string in the following format YYYY-mm-dd * data[User][gender] - required, could be either "male" or "female" * data[User][postcode] - optional UK postcode format. * data[User][toc] - required value should be 1 Optinally if you are passing the auth token from third party sites such as facebook, twitter and later g+ extra data will be used: * data[fb][access_token] - access token from facebook * data[twt][access_token] - json object containing string like: {"oauth_token":"...", "oauth_token_secret":"..."} * data[g+][access_token] - access token from Google+ (TODO) Response: json string. In the response string you can see userid as well as hash string. By using them, you don't need to make second login call. Forgot password ------------------------------ If you pass an email which is linked with social login (e.g. Facebook or Twitter) then an 'error' will appear like: This email is linked with Facebook please log in with facebook. Along with the message there will be a flag 'try_social' which will be true. If you have this flag, it's good if you could show the social sign-up buttons along with the error message. URL: https://licklist.co.uk/forgot-password.json Header: none Parameters: $_POST[email] - required, string Response: json string Reset Password ------------------------------ URL: https://licklist.co.uk/reset-password.json Header: none Parameters: $_POST[id] - required, string - id of the user. (It should be provided from the forgot password email link) $_POST[token] - required, string - (token is send with forgot password email) $_POST[password] - required, string - the new user's password $_POST[password_again] - required, string - passwords must match Response: json string Facebook Login/Register ------------------------------ *The access point act as router which do following: 1. If the user is not registered fetch the data from facebook and return the array which need to be passed to the registration form. 2. If the user is registered, attempt to login it based on access token of the user and return logged in response ( similar if the user login using email/password) The workflow here is: 1. User open the app and lick over Facebook button 2. The app get the FB token from facebook.com 3. The app pass the token to that api call and depending if the user is registered or not the data is returned 4. The app should then returect the user to logged in screen (if the user already is registered) or display the registration form and populate the fields with data from the response. The distinction between that user is logged in or need to be registered is in data[User][id] or if there is node data[User][hash]. If there is, it mean that user is logged and hash can be used for further authentication If the user provide invalid token an error will be returned* URL: https://licklist.co.uk/fb.json Header: none Parameters: $_POST['access_token'] - Facebook access token provided from facebook Response: json string Check unique email/phone ------------------------------ URL: https://licklist.co.uk/users/validate/email.json https://licklist.co.uk/users/validate/phone.json Header: none Parameters: $_REQUEST['value'] - required, string - value which need to be checked for uniqueness $_REQUEST['field'] - optional, string - name of the field from which is taken the value (used for desktop validation) Response: json which contain valid node which indicate is it valid or not and validation message if the value is not valid for some reason or already exists Lick ------------------------------ URL: https://licklist.co.uk/lick.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['object_type'] : required, string, - object type which is licked (MediaCollection, Venue, GoingOut, Review, Comment, etc.). It should be taken from the previous response which provide the data on the screen. (can be used also $_REQUEST[type]) $_REQUEST['object_id'] : required, integer, object id which is licked. It should be taken from the previous response. (can be used also $_REQUEST[id]) Response: json string User Tooltip ------------------------------ * The tooltip is suitable for mouse enabled devices (desktop) because it should be enabled when user hover the mouse on some link * URL: https://licklist.co.uk/users/tooltip.json or https://licklist.co.uk/users/tooltip/[USER-ID].json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] : required, integer - id of the user which is requested Response: json string Venue Tooltip ------------------------------ * The tooltip is suitable for mouse enabled devices (desktop) because it should be enabled when user hover the mouse on some link * URL: https://licklist.co.uk/venues/tooltip.json or https://licklist.co.uk/venues/tooltip/[USER-ID].json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] : required, integer, id of the venue which is requested Response: json string Search ------------------------------ * Provide search functionality of the site. The search can be used to filter some lists such as: Users only ordered by specific location (use lat,lng with order=location and object=user) Venues only ordered by specific location (used in the map search as well - use lat,lng with order=location and object=user)* URL: https://licklist.co.uk/search.json Header: none, See "Secondary requests" section for reference Parameters: $_REQUEST['q'] : optional, string - this is the search string. If the variable is empty it will display generic results. $_REQUEST['index'] : optional, string - defaults to 'search', this is what index to use for search. Currently there are 3 indices: search : which contain everything but events & offers are limited up to current date. This mean that only actual events and offers will be shown in the index. object_related: data related to object like 'venue', 'festival', 'dj' etc. this data could contain related object to the parent. Example: On venue page there is a list of latest things from the venue. The "things" are events, offers, galleries (MediaCollection), Reviews (todo), updates etc. This index contain all the data without date restriction. It should be used to generate list of events, list of offers, etc. autocomplete: Used for autocomplete. This index search only in the names of the entries, so it's quite limited. Avoid using it, use autocomplete call instead. See 'Autocomplete Search' $_REQUEST['start'] : optional, integer - defaults to 0, this is the offset of the list. increment that parameter with the number of results on the screen in order to get next result set. $_REQUEST['limit'] : optional, integer, less than site page limit. Currently on the site, one page could have 12 results, by limit you can get less than 12 results. For example you can select 10 results or 5, but if you pass 15 or 20 it will return 12 $_REQUEST['order'] : optional, string, order which will be used to order the results. Currently there are 4 orders: relevance (default), name, location, licks, rating, created (created date), date (records which has date, Event, GoingOutCache etc). While licks and rating are relevant to venue (or festival, dj, user's doesn't have licks neither rating), if 'licks' or 'rating' is selected, the second order criteria will be name. $_REQUEST['lat'] : optional, decimal - This is latitude of the map from where the search starts. $_REQUEST['lng'] : optional, decimal - This is longitude of the map from where the search starts if you pass lat and lng it's good to pass also order by location, otherwise the location doesn't make sense. So ideally, if you pass lat and lng it should come together with order=location. This poing could be user's location, but it could be any point on the map. Example - venues on the map sorted by nearest location. Lat and lng comes together, so you should use them together. $_REQUEST['template'] : optional, string, This parameter is not suitable for mobile development, but it is handy if you work with html. Along with .hson extension it will return nodes ready to be assigned to the dom. Currently there are 4 templates: list, grid, autocomplete (used in search autocomplete), map $_REQUEST['radius'] : optional, integer, This variable working only with lat and lng provided. It filter the results within specified radius in Meters from the specified geo location (lat, lng). Mainly this will be used for Auto check-in functionality. $_REQUEST['filter']['FIELD'] : optional,string - Ability to filter the result by specific field. FIELD part could be replaced with some values from the existing fields of the record. Possible record fields are: id - integer object - string date - date parent_object - string parent_id - integer county_id - integer town_id - integer membership - integer (possible value 1) whether the venue is in the membership programme Additional Goingout Filters available for indices: goingout_users & goingout_users_objects user_gender - string (male|female) user_id - integer user_type - string (regular|facebook) whether user is licklist one or imported user_photo - boolean (1|0) - whether user has image or not For example the field could be: $_REQUEST['filter']['object']=event &filter[object]=event or $_REQUEST['filter']['object']=event,offer &filter[object]=event,offer or $_REQUEST['filter']['date']=(2014-01-01,2014-01-31) &filter[date]=(2014-01-01,2014-01-31) Side Notes: The first example will search for exact value in the field object. This will filter results to be only 'events'. The second example will be search for objects which match 'event' OR 'offer'. The third example will search for interval between first date and the second one. Please note that this could be used for integer or date fields. TODO (deprecated) Added filter[home]=1 (working only for object GoingOut) it will fetch goingout entries which are good looking. Added filter[photo]=original - if you pass that parameter user's photos will be original images instead of default 200x200 (Extra predefined obhect values): There are couple of predefined filter[object] values: all - a complex type which will return (object=Venue and object=User) OR (object=Event and date) nightclubs - return (object=Venue and type=nightclub) bars - return (object=Venue and type=bars) events - return (object=Event and date (if not set default to today onwards)) festivals - return (object=Festival and unset date if passed) venues - return (object=Venue and unset date if passed) event-brands - return (object=Venue and type=Promoter) $_REQUEST['partition'] : (boolean) used to split the results in groups. This var working with filter[object] Basically the if you pass filter[object] as array of values it will split the results in groups like $_REQUEST['object'] : (deprecated, use filter[FIELD] instead) optional, string - It can specify what data type can be searched. For example you can request $_REQUEST['object']=user and it will search only users, or venues. The variable can be combination of comma separated terms like $_REQUEST['object']=user,venue Currently there are 4 types of search: venues, users, events, offers Later on it could have also gallery, review, festival etc. General rule: objects are singular lowercase (user, event,venue, etc.) $_REQUEST['parent_type'] : (deprecated, use filter[FIELD] instead) optional, string, this can filter data by parent type. Let's say in the index you want to search for all events which belongs to a 'venue'. If so, parent_type=venue need to be passed and it will return relevant data. $_REQUEST['parent_id'] : (deprecated, use filter[FIELD] instead) optional, integer, this should work together with parent_type. if both parameters are set the result will contain items which belong to particular object. As example if you want to filter data which belongs to 'venue' with id 22 you need to pass: parent_type=venue&parent_id=22. $_REQUEST['collections'] : if you pass parameter collections, the results will have a node for collection groups Response: json string. Every node will hold "object" attribute which will identify the type of the node. Currently there are 4 types of data, in the future they will be increated. So far: User, Venue, Offer, Event (on later stage it will be added MediaCollection (gallery) and probably Reviews). Autocomplete Search ------------------------------ *The autocomplete search search in the Venues, Event and Users names and provide autocomplete functionality for the search. Please note that this return only up to 10 results and it search in the name field only (it looking only from the beginning onwards, as every normal autocomplete), so shouldn't be used for full search* URL: https://licklist.co.uk/autocomplete.json Header: none, See "Secondary requests" section for reference Parameters: $_REQUEST['q'] : string which should be searched. $_REQUEST['index'] : optional, string could accept autocomplete & autocomplete_venues. If it's the second one, then only venues will be provided. $_REQUEST['extra'] : if the variable exists, the data is moved under 'data' node, and new node 'counts' is added which identify if there are results under each object type. This is convenient to handle autocomplete similar to facebook, where you can add nodes like: 'Search [venues|users|events] named "some string"' Response: json List of entries Friends Autocomplete ------------------------------ *This call should be used to get friends or mutual friends in autocomplete when user tag a photo, or in the future in mentions* URL: https://licklist.co.uk/friends/autocomplete.json Header: none, See "Secondary requests" section for reference Parameters: $_REQUEST['q'] - optional, string - used to search users by name (start of the name) $_REQUEST['limit'] - optional, integer - how many results to return. It should be number less than default list number (12). Otherwise, the result is 12. N.B. start is omitted, because it's autocomplete, and it should provide first set of results only. $_REQUEST['type'] - optional, string (for now it's only ImageTag) $_REQUEST['object_type'] - optional, string (for now it's only Upload) $_REQUEST['object_id'] - optional, integer (id of the tagged Upload) N.B. type, object_type and object_id are used to filter users which are already tagged on the Upload. If you want to remove already tagged users, then you need to include all these 3 parameters in the request. Otherwise the list will return friends, mutual friends and the logged user too. Upload a file ------------------------------ *This action just upload the file into the server, without storing it into the database. See "Store A file" Section for further instructions. The call is aplicable only to photos, which could have preview. If the uploaded file is not image (jpg,png,gif) it will return error message. Video files are not stored this way, because there is no preview for them, since they need to be converted in third party site before they are published* URL: https://licklist.co.uk/uploading.json Header: See "Secondary requests" section for reference Parameters: $_FILES['file'] : required, Array of the uploaded file through POST method. The array should contain the standard attributes of the uploaded file. Example: name, type, tmp_name, size, error. Optially this can contain array of array of uploaded files like $_FILES['file'] = [{name, type, tmp_name, size, error}, {name, type, tmp_name, size, error}, ...] $_REQUEST['filename'] : optional, string - If you want to change the name of the variable $_FILES['file'] for example $_FILES['somefile'] pass the string like $_REQUEST['filename']=somefile and the script will check $_FILES['somefile'] for file uploaded. Response: Return json string containing file node which has url for the file uploaded on the server. The file return also width, height and ratio, which especially is useful if the image need to be displayed on the string. If the files uploaded are more than one then the result will contain node "results" which will contain an array of individual file upload results. Store a file ------------------------------ * This action will store uploaded file to the database, or if it's directly uploaded through this action, it will store it to the database as well. The previous step (Upload a file) is used for ajax upload a file and this step just store it into the db. * URL: https://licklist.co.uk/uploads/store.json Header: See "Secondary requests" section for reference Parameters: $_POST['type'] : required, string - the parent object of the file. For example it could be MediaCollection, Event, Venue, VenueCover etc. For the API calls, only the MediaCollection is suitable, the other ones required admin rights, which most of users wont have, and it will fail to save anything. The parameter could accept another 2 special types: user-media : (lowercase) this will store the upload into user's default gallery profile-media : this will store the uploadr into user's default gallery AND it will make the photo (if it's photo) user's profile image. Setting this you could pass extra parameters such as: width, height, x and y which will be used as cropping guideline. If they are skipped, the image will be cropped automatically as square and centered. cover-media : This will store the upload into user's default gallery AND it will make the photo (if it's photo) user's cover image. (see profile-media for more details) $_POST['id'] : optional, integer - the parent object id (if known). Can be skipped, if the type is specific string see 'type' parameter. $_FILES['file'] : optional (if $_POST['file'] is set) - Array of the uploaded file through POST method. The array should contain the standard attributes of the uploaded file. Example: name, type, tmp_name, size, error. Optially this can contain array of array of uploaded files like $_FILES['file'] = [{name, type, tmp_name, size, error}, {name, type, tmp_name, size, error}, ...] $_POST['file'] : optional (if $_FILES['file'] is set) - mixed (string or array) of files which should be stored. This should be the url of the file which is returned from "Upload a file" option or array of that files. Example: $_POST['file'] = 'http://static.licklist.co.uk/photo/preview/tfL0XNiKTimvzqaV.jpg'; OR $_POST['file'] = ['http://static.licklist.co.uk/photo/preview/tfL0XNiKTimvzqaV.jpg', 'http://static. licklist.co.uk/photo/preview/IjWq02aLIlcRbC15.jpg']; $_POST['width'] : optional, integer - used if the type is set to 'profile'. width of the selection $_POST['height']: optional, integer - used if the type is set to 'profile'. height of the selection $_POST['x'] : optional, integer - used if the type is set to 'profile'. left offset of the selection $_POST['y'] : optional, integer - used if the type is set to 'profile'. top offset of the selection Response: Return json contains the id of the uploaded file, or multiple ids (depending how many files are uploaded) List files ------------------------------ *Action will get a list of files within a MediaCollection (gallery) and it will return them as a list. The difference between this call and /media-collection/view/1 is that the other one will have a node with media collection details too* URL: https://licklist.co.uk/uploads.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['type'] : required, string - Defaults to MediaCollection, but in the future it can also be User, Venue, Festival etc. $_REQUEST['id'] : required, integer - id of the media collection which contain the list of files $_REQUEST['start'] : optional, integer - defaults to 0, offset of the list $_REQUEST['limit'] : optional, integer - defaults to LIST_LIMIT which is 12 at the moment $_REQUEST['fields'] : optional, string - additional attributes which could be requested for each Upload. Provide them as comma separated list like $_REQUEST['fields']=views,comments,...: Possible parameters: views - total number of views comments - total number of comments licks - total number of licks grab - whether the foto can be grabbed or not (boolean) (attribute canGrab) Response: Json string of Uploads List files - Media Collection ------------------------------ *Difference between this and "List files" is that this one has Media Collection details included which is useful if a details section need to be created (header of the gallery). Apart from this, all other options which are valid for "List files" are valid for this one as well. Fields parameter need to be encapsulated to Upload.fields(views,...) instead of only comma separated list.* URL: https://licklist.co.uk/gallery.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] : required, integer - id of the media collection which contain the list of files $_REQUEST['start'] : optional, integer - defaults to 0, offset of the list of uploads $_REQUEST['limit'] : optional, integer - defaults to LIST_LIMIT which is 12 at the moment $_REQUEST['fields'] : optional, string - additional attributes which could fetch extra relations for the record. Provide them as comma separated list like $_REQUEST['fields']=views,comments,...: Possible parameters: views - total number of views comments - total number of comments licks - total number of licks grab - whether the foto can be grabbed or not (boolean) (attribute canGrab) Example of fields parameter in that call: $_REQUEST['fields']=views,comments,Upload.fields(views,comments) This one will load views, comments of MediaCollection record, as well as views and comments on Upload records Response: Json string containing 'data' row of MediaCollection and Upload - array of uploads under the media View File ------------------------------ *This call should be used for single image preview. With it can be created gallery* URL: https://licklist.co.uk/media.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] : required, integer - id of the media Response: Json string containing 'data' row of Upload Delete Upload ------------------------------ *Logged user can delete upload from his collection. This also include grabbed objects* URL: https://licklist.co.uk/uploads/delete.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] : required, integer - id of the Upload Response: Json string containing result of the operation Favourite Venue ------------------------------ *Make some venues user's favourite. The call act as toggle of the state. So, be careful with the multiple venues, since some could be favourited, some un-favourited* URL: https://licklist.co.uk/venues/favourite.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['venues'] : required, mixedid of the venue which user want to make it facourite. The parameter could be integer - single venue id string - comma separated list of venue ids array - flat array of venue ids which user want to make favourite. $_REQUEST['start'] : optional, integer offset Response: Json string return if the venue is facourite or not Note: If the parameter venues is omitted the the response will return the favourite venues of the user Request Friendship ------------------------------ *Toggle friendship between users. This function should be used carefully, since it acts as toggle of the state. This mean if the users are already friends it will remove the friendship and the user(s) need to make friend request again* URL: https://licklist.co.uk/friends/friendship.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['friends'] : required, mixed - friend(s) ids. This parameter could be: integer - single user id string - comma separated list of users ids array - flat array of users ids Response: Json string return the status of the current friendship. There are 4 states of the friendship: false : users are not friends true : you requested yourself for friendship request-pending : friendship is requested, but the other user still doesn't accept it pending-request : the other user has been sent a friend request, and it need an action to be accepted accepted : users are friends Check Friendship Status ------------------------------ *It gives information what is the relationship between logged user and another user* URL: https://licklist.co.uk/friends/status.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] : required, integer - id of the user which is requested against the logged user Response: Return the status of the relation. There are 4 states of the friendship: false : users are not friends true : you requested yourself for friendship request-pending : friendship is requested, but the other user still doesn't accept it pending-request : the other user has been sent a friend request, and it need an action to be accepted accepted : users are friends Delete Friendship ------------------------------ *Delete friendship between logged user and one or many other users* URL: https://licklist.co.uk/friends/delete.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['friends'] : required, mixed - friend(s) ids. This parameter could be: integer - single user id string - comma separated list of users ids array - flat array of users ids Response: Json, return always true, since this operation make delete only. It's an indicator when the process is over. Set Profile Media from existing file ------------------------------ *This call will set specified image from user's gallery as profile image* URL: https://licklist.co.uk/profile-media/store.json Header: See "Secondary requests" section for reference Parameters: $_POST['id'] : required, integer - id of the Upload selected from user's gallery. $_POST['width'] : optional, integer - used if the type is set to 'profile'. width of the selection $_POST['height']: optional, integer - used if the type is set to 'profile'. height of the selection $_POST['x'] : optional, integer - used if the type is set to 'profile'. left offset of the selection $_POST['y'] : optional, integer - used if the type is set to 'profile'. top offset of the selection $_POST['type'] : optional, string - could be either 'photo' or 'cover' (defaults to photo). If it's photo, this will be user's profile image, if it's cover, then it will be cover. Response: Return if the operation is successfull or false (display the error message why). Venue Details ------------------------------ *This is used to construct venue details page. The call is used to fetch the venue data + 3 uploads from latest venue gallery. The "Latest from Venue" section should be done as separate call with /search* URL: https://licklist.co.uk/venue.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] : required, integer - id of the Venue. Response: Return json data of the venue. There are also 3 Venues for latest galleries included under MediaCollection. Read LikeDislike for explanation of 'like_dislike' node. LikeDislike ------------------------------ *The call is used to make some object to be liked, as well as there is dislike. User should be able to like Venue, Festival, Dj or similar objects. The call act as toggler, if you set like (1) then the likes are increased, while if you send the call again (1) the like will be removed. If the user like and then change his mind, the state has been changed so it doesn't need to be toggled and then send another status. LikeDislike shouldn't be mixed with licks. When user like something the lick is increased by one. If user doesn't like it (dislike) the lick is removed. LikeDislike participate in the Rating calculation as well. When some object contain 'like_dislike' node (venue details call for example) it could have 3 states: 1 - the logged user liked the object 0 - the logged user disliked the object. null - the logged user doesn't make likedislike action so far As example: user like Venue 22, it add one like to Venue 22. If user click over the button again the entry will be removed, like the user never get clicked over this. If user like Venue 22 (like is added again), then user click over the dislike, then the like automatiaclly is converted to dislike.* URL: https://licklist.co.uk/like-dislike/liking.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['type'] : required, string - type of the object which is liked. Could be 'Venue', 'Festival', 'Dj' etc. $_REQUEST['id'] : required, integer - id of the liked object. $_REQUEST['status'] : required, boolean - status could be either 1 (I like it) or 0 (I dislike it) Response: It return following data: dislike : number of dislikes like : number of likes total : total likes and disliked (sum) rating : object average rating licks : object average licks status : what is user's resolution for the current object: could be: 1 - the logged user liked the object 0 - the logged user disliked the object. null - the logged user doesn't make likedislike action so far (user toggled his previous action) Comment Add ------------------------------ *Comments can be "attached" to any object which make sense. For example, under photo, gallery, event, offer etc.* URL: https://licklist.co.uk/comments/add.json Header: See "Secondary requests" section for reference Parameters: $_POST['object_type'] : required, string - type of the object which is liked. Could be 'Upload', 'MediaCollection', 'Event', 'Offer', 'Review' etc. $_POST['object_id'] : required, integer - id of the liked object. $_POST['text'] : required, text - this is the coment's text Response If will return json with currently inserted comment, or error message if for some reason the comment failed Comments ------------------------------ *It will return existing comments of the specified object* URL: https://licklist.co.uk/comments.json Header: None, See "Secondary requests" section for reference Parameters: $_REQUEST['object_type'] : required, string - type of the object which is liked. Could be 'Upload', 'MediaCollection', 'Event', 'Offer', 'Review' etc. $_REQUEST['object_id'] : required, integer - id of the liked object. $_REQUEST['start'] : Offset of the list $_REQUEST['limit'] : how many comments to be displayed. By default it will show site's default number of comments (12), if you specify it it can display 1 to 12 comments. This is useful if you want to display initially 3 to 5 comments, and then if the user want to display the rest of the comments. Response: It will return list of comments as well as node containing the total number of comments in the thread. N.B. Results are returned ordered by ID DESC, this mean the newest comments are first. If you want to display them in chronological order you need to make this when placing them in the parent container. Comments Delete ------------------------------ URL: https://licklist.co.uk/comments/delete.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] : id of the record Response: json with status of the action or error Report Add ------------------------------ *You can fill a report for any content on the site. Report will send an email to the admins and they could take the necessary actions to remove the content if needed.* URL: https://licklist.co.uk/reports/add.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['object_type'] : required, string - type of the object which is reported, could be 'Upload', 'MediaCollection', 'Review', etc. $_REQUEST['object_id'] : required, integer - id of the object $_REQUEST['description'] : string, optional - what is the reason to report the object $_REQUEST['type'] : string, optional - provide it if you want to receive a structured text as response. possible values: 'dont-like', 'inappropriate' Example: if you pass 'dont-like' the response will be : Ah that's a shame, we liked that photo! But not to worry, this photo will now be removed from the Licklist network within 24 hours. Response: json with status of the action or error Grab Upload ------------------------------ *User could grab any public photo (in the future also video) and add into his collection. Grab itself is not phisical copy of the image, rather than just a reference to the original one. If the original image has been deleted, the grab will be deleted as well. Grab an Upload can happen only once.* URL: https://licklist.co.uk/grabs/add.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['object_id'] : required, mixed - id(s) of the object The value could be either id of single Upload, or comma separated list of ids. Response: It will return if the grab is successful or not. If there are multiple values, the result will return data{} object with status of each grab. Latest Public Grabs ------------------------------ *This is a public access of the latest 24 grabs from the users. It could be used to feed the homepage of the app* URL: https://licklist.co.uk/grabs/index.json Header: See "Secondary requests" section for reference Response: It will return 24 results in the data node and under each node there will be the Upload object with url of the photo and gallery from where it has been taken (object_type, object_id). Add Upload Tag ------------------------------ *Tags can be assigned to Upload. Usually on Photos. Tags can be a point on the image (with some radius) or just a label that there is a tag on the Upload (usually tag without coord is for Videos). User can tag over Venue images (without restriction) as well as user photos only if they are friends (this is done on the server, but need to be prevented in the UI).* URL: https://licklist.co.uk/image-tags/add.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['object_id'] - required, integer - id of the upload wihch will be tagged $_REQUEST['tags'] - required, array - tags could be multidimensional array or flat array here is the common attributes of the flat array: * user_id - optional, integer - id of the user which has been tagged, this could be skipped if name is provided * name - optional, string - could be skipped if user_id is provided. This gives ability to tag non existing user on the Upload * x - optional, decimal - horizontal position of the tag in the image * y - optional, decimal - vertical position of the tag in the image * r - optional, decimal - radius of the tag N.B. x, y and z can me omitted, since the tag could be assigned without dot on the image. tags could support multiple tags by providing array of arrays as described above. Response: json containing the data of the created tags. If the tags are multiple the response will contain multiple results too. Delete Tag ------------------------------ *Tags could be deleted from: creator of the tag, tagged person, or admin* URL: https://licklist.co.uk/image-tags/delete.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] - required, integer - id of the tag Response: json state of the operation. If couldn't delete the tag it will return also error message. Event Details ------------------------------ URL: https://licklist.co.uk/events/view.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] - required, integer - id of the event Response: json details of the event. In the response there are up to 12 users which will be going to that event. Event list ------------------------------ Use Search call with filter[object]=Event Offer Details ------------------------------ URL: https://licklist.co.uk/offers/view.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] - required, integer - id of the offer Response: json details of the offer Offers list ------------------------------ Use Search call with filter[object]=Offer Reviews List ------------------------------ URL: https://licklist.co.uk/reviews.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['object_type'] - required, string - type of the parent (usually Venue) $_REQUEST['object_id'] - required, integer - id of the parent $_REQUEST['start'] - optional, integer - default to 0 offset of the list Response: json list of reviews Review View ------------------------------ URL: https://licklist.co.uk/reviews/view.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] - required, integer - id of the review Response: json details of the review The response contain the following important nodes: - User - user who wrote the review - Users - are users which have been with the person who wrote the review - Venues - are venues which has been visited in the specified night. Both Users and Venues on 'type'=night could be empty If the type is 'venue', then a node 'Venue' & 'Reviewed' will be on the result Review Store ------------------------------ URL: https://licklist.co.uk/reviews/store.json Header: See "Secondary requests" section for reference Parameters: Following post parameters need to be submitted in $_POST * data[Review][id] - optional, integer if it's provided a valid review, then the save will modify the existing record * data[Review][object_type] - required, string (could be either 'night' or 'venue') * data[Review][object_id] - optional, integer (the field is required if the 'type' above is 'venue') * data[Review][title] - required, string * data[Review][description] - required, string * data[Review][visit_date] - optional, date, the field is required if the type is 'night' * data[Review][Rating] - required, array containing key=>value data of the review ratings Example: data[Review][Rating][drinkvalue]=3 (see the Ratings List call to view available options) When the form is created a call to Ratings List with type will fetch the available ratings Response: Return status of the operation and id of the successfull review. Review list ------------------------------ Use Search call with filter[object]=Review Ratings list ------------------------------ URL: https://licklist.co.uk/reviews/ratings.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['type'] - required, string could be 'Venue' or other object such as 'Festival' or 'Dj' (for now only 'Venue') Response: json of available ratings where under data the key is what it should be passed in the Review form, and value is the label News View ------------------------------ URL: https://licklist.co.uk/news/view.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] - required, integer - id of the news Response: json details of the review Bead in mind that contents of the news is HTML string which could contain images too. News list ------------------------------ Use Search call with filter[object]=News User View (profile page) ------------------------------ URL: https://licklist.co.uk/users/view.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] - optional, integer - id of the user, if missing, the profile will be on the logged user. Response: json details of the User List User Uploads ------------------------------ Currently all upload which user uploaded + all uploads which user has been tagged + all uploads which user has been grabbed appear in one virtual gallery. URL: https://licklist.co.uk/media-collections/user.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] - optional, integer - id of the user, if missing, the gallery will be on the logged user. $_REQUEST['start'] - optional, integer - default to 0 offset of the list $_REQUEST['limit'] - option, integer - defaults to site's max page entries Response: json containing User/Owner Details and Uploads. List User Reviews ------------------------------ Because the list is only from one user, it's better the image on the UI to be the venue one. URL: https://licklist.co.uk/reviews/user.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] - optional, integer - id of the user, if missing, the reviews will be on the logged user. $_REQUEST['start'] - optional, integer - default to 0 offset of the list $_REQUEST['limit'] - option, integer - defaults to site's max page entries Response: json containing data User/Owner and Reviews List Venue Updates ------------------------------ URL: https://licklist.co.uk/updates/index.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] - required, integer - id of the venue $_REQUEST['start'] - optional, integer - default to 0 offset of the list $_REQUEST['limit'] - option, integer - defaults to site's max page entries Response: json containing data Venue/Owner and Updates Who's Doing What List ------------------------------ Use Search call with parameter: index=goingout_users - set the proper index filter[date]=(2014/01/01,) search for ongoing events only the date 2014/01/01 should be replaced with currently date in format yyyy/mm/dd order=date - set goingout date asc Example: https://licklist.co.uk/search.json?index=goingout_users&filter[date]=(2014/01/01,)&order=date https://licklist.co.uk/search.json?start=0&lat=51.545927&lng=0.707712000000015&index=goingout_users&order=date,location Who's Going List ------------------------------ Similar as Who's Doing What, but here use another index: index=goingout_users_objects and filter by parent_type and parent_id (see the example) This will give you information for users which are going to that specific venue from current date onwards Example https://licklist.co.uk/search.json?index=goingout_users_objects&filter[date]=(2014/01/01,)&order=date&filter[parent_id]=22&filter[parent_type]=Venue User's Hub ------------------------------ This call will display the user's activity across the site. The structure of the data follow these principles: /Who - The node could contain 1 or more User objects. This are the participants who (or to whom) do the action (e.g. wrote a review, grab a photo, write goingout post etc.) In the case of User's hub this will be always the same user. /What - this is the object which the user interacted with (e.g. the review). In some cases this is the parent object which user interact with. For example, if user has been tagged in few photos of a Venue, the who will be the Gallery which contain the uploads. /Objects - this is 1 or more objects with the same parameters as in the search results. The objects will be of the same type, so when user Grabbed some photos the /Objects will contain only Upload objects. Example: If User has been tagged in some photos of a Venue's MediaCollection, the Objects will contain these Uploads. N.B. while the user could interact with many objects only first few of them are returned in the Objects array, the total number of objects could be found in /total node. /action_type - the type of the action which has been taken: e.g. Review, Grab, Tag this should be an Object notation. /action - could distinct further the post. For example goingout post initially will be in the hub of the autor of the post, but if the author selected some users which will come with him that night, all these users could have similar posts, but their action will be goingout-with. Having these nodes the Hub post consist of the following parts: * Side photo - this is the First Photo of the /Who's array. Usually this will be under /Who/0/Photo path (first object) * Activity - A sentence which contain some parts which should be replaced with the proper names (Explained below) * Details - An object (or objects) which have the same structure as the Search results, but with slightly different design. Activity part of the Hub post is a text sentence which contain some placeholders which should be populated when the post has been constructed. As example: Martin has been tagged in some photos of Evoke gallery: {/Who/name} was tagged on 2 photos of {/What/Owner/name}'s gallery {/Who/name} - should be Replaced with the data[Who][name] (Martin) and {/What/Owner/name} - should be replaced with data[What][Owner][name] When you create the replacer function try to make it in such way that it will handle multidimensional arrays. For example: if data[Who] contain more than one object (let's say 5) the script should get the names in the following way: {/Who/0/name, /Who/1/name and /Who/2/name and 2 more}, will become Martin Saunders, Brad Nobbs and Nik Cankov and 2 more grabbed some photos of ... URL: https://licklist.co.uk/status/hub.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['start'] - optional, integer - default to 0 offset of the list $_REQUEST['limit'] - option, integer - defaults to site's max page entries Response: json GoingOut Post ------------------------------ Post user's status. This call will be used to store regular goingout post. There is another call see: "GoingOut Event" section URL: https://licklist.co.uk/going-outs/store.json Header: See "Secondary requests" section for reference Parameters: Following post parameters need to be submitted in $_POST * data[GoingOut][id] - optional, integer if it's provided a valid review, then the save will modify the existing record * data[GoingOut][date] - required, date when the user is going out * data[GoingOut][description] - optional, text storing user's message to that post * data[GoingOutUser][user_id][] - optional, array user_id's which are "invited" to go with the user (Author of the post) * data[GoingOutVenue][venue_id][] - optional, array venue_id's where user is planning to go Response: json GoingOut Event ------------------------------ This call could be used on even'ts detail page where user can click on a button "I am going" or "not going". This should be combined with isGoing node of event's call. N.B. This call act as toggle, so if it's used when the event's node isGoing is true, then it will remove the goingout post. URL: https://licklist.co.uk/going-outs/going.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['object_id'] - required, integer, id of the event Response: json GoingOut View ------------------------------ URL: https://licklist.co.uk/going-outs/view.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] - required, integer, id of the goingout Response: json User settings ------------------------------ This is the default settings call, which store the data in the user's table. There could be other calls later on which will store the user's preferences like privacy, profile settings (type of music, type of drinks etc). The call make the same as Registration, just saves the data to the currently logged user. URL: https://licklist.co.uk/settings.json Header: See "Secondary requests" section for reference Parameters: data need to be passed with the following notation: data[User][field] = [VALUE] Example: data[User][first_name] = "John" All Parameters which need to be passed are (all parameters should be passed as $_POST): * data[User][first_name] - required, string * data[User][last_name] - required, string * data[User][password] - required, string * data[User][phone] - required, 11+ digits, no space no dash * data[User][birthday] - required, could be date in the following format YYYY-mm-dd or data[User][birthday][] - first element - day data[User][birthday][] - second element - month data[User][birthday][] - third element - year From the array should be able to be created date string in the following format YYYY-mm-dd * data[User][gender] - required, could be either "male" or "female" * data[User][postcode] - optional UK postcode format. * data[User][description] - optional user's short "About me" section. Privacy settings * data[User][settings][privacy][global] - required (preselected with everyone), with 2 values - everyone and friends * data[User][settings][privacy][age] - required (preselected with everyone), with 2 values - everyone and me * data[User][settings][privacy][location] - required (preselected with everyone), with 2 values - everyone and friends Notification Settings Notifications for friend requests data[User][settings][Notification][email][Friend] - optional (preselected as checked), value 0 or 1 data[User][settings][Notification][mobile][Friend] - see above Notifications for comments data[User][settings][Notification][email][Comment] - optional (preselected as checked), value 0 or 1 data[User][settings][Notification][mobile][Comment] - see above Notifications for user tagging data[User][settings][Notification][email][ImageTag] - optional (preselected as checked), value 0 or 1 data[User][settings][Notification][mobile][ImageTag] - see above Response: json N.B. Email for now is not possible to be changed with this call. There should be separate call which will send an email with some code which user need to click over a link in order to change the email (we are interested to have user's real email) Competition list ------------------------------ Return list of competitions URL: https://licklist.co.uk/competitions/index.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['start'] - optional, integer - default to 0 offset of the list $_REQUEST['limit'] - option, integer - defaults to site's max page entries $_REQUEST['archive'] = optional, if it's omitted it will display only active competition Response: json Competition details ------------------------------ URL: https://licklist.co.uk/competitions/view.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] - required, integer - id of the competition Response: json Note: in the response there is a node participated which indicate if the user participated in the competition. If so, disable functionality to enter the competition. Competition participation ------------------------------ URL: https://licklist.co.uk/competitions/enter.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] - required, integer - id of the competition $_REQUEST['answer'] - required, integer - available answer from the competition answers Response: json Check-in functionality ------------------------------ Mobile users should be prompted if the are next to some venues and they don't move (if the user has been stopped try to find the nearby venues) The workflow should be as follows: 1. User walk (no action) 2. User stop (no action) 3. Second check and user is near to his previous location (server check location provided) and if there are venues around and user allowed check-in from his profile send push notification and of course user registered his phone in the network, then push notification will be sent. 4. Once the notification has been sent (push) the user should be prompted to check available venues around. This should be done with search call with radius parameter specified. 5. From the list user should be able to select a venue and with api call it will check him in to the specified venue. 6. When the user is moved away from the checked venue the phone should make checkout call which will check-out the user from his last location and it will return him into moving state. Check-in checkin ------------------------------ URL: https://licklist.co.uk/checkins/checkin.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['object_type'] - required, string - type of the object (should be taken from the list of venues arround) could be Venue, Festival etc. $_REQUEST['object_id'] - required, integer - id of the object Response: json Note: This call check-in the user only the first time. The second call if the user is not checked out will return error message, but it shouldn't be concidered as error rather than a warning. Check-in checkout ------------------------------ URL: https://licklist.co.uk/checkins/checkout.json Header: See "Secondary requests" section for reference Response: json Check-in is checked-in ------------------------------ This is utility call, it shouldn't be used. URL: https://licklist.co.uk/checkins/checked.json Header: See "Secondary requests" section for reference Response: json Check-in status ------------------------------ This call will send push notification once called regularly. It's not needed if the phone itself detect when the user has been stopped. URL: https://licklist.co.uk/checkins/status.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['lat'] - required, double, latitude $_REQUEST['lng'] - required, double, longitude Response: json Note: If it's used it should be called in certain interval (e.g. on every 15 min). Check-in users ------------------------------ This call should be used to display users which are in the specific venue URL: https://licklist.co.uk/checkins/users.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['object_type'] - required, string, type of the object (venue usually) $_REQUEST['object_id'] - required, integer, id of the venue Response: json, containing 'data' as users which are in that venue (other checkins) and 'total' which is the all users (incl. the users in data attr) Loyalty lick offers / Redeemable ------------------------------ Loyalty lick offers are exclusive offers which user can redeem only with the points which he earned from the site. For some actions like Writing a review, writing gogin-out post licking something the user earns points which are added into his account balance. The offers which are exclusive had parameter 'exclusive' which should be bigger than 0. These offers could be redeemed from the site and used later in the venue. The workflow is: 1. User spot an offer on the site which is marked as exclusive 2. User decide to redeem it and click the button "Save to my offers" 3. User go to the specified venue and decide to use the offer 4. He go to the bar (show it to the bar staff) and in order to activate it he need to press a button indicating the offer is used 5. Once it's active the offer shouldn't be possible to be used again User could delete the offer and user's points need to be bigger than the offer's "price" of points. The offer which is exclusive has a parameter "canRedeem" which indicate whether use can redeem the offer or not and depending from it the offer should display the button to redeem or not. Note: In addition, in the list of redeemed offers it's possible to see also rewards. Rewards are added when the user refer a ticket event (referral). List of redeemed offers ------------------------------ URL: https://licklist.co.uk/redeemables/index.json (old url) https://licklist.co.uk/offers-redeems/index.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['start'] - optional, integer, offset $_REQUEST['limit'] - optional, integer, limit $_REQUEST['active'] - optional, boolean, defaults to 1, it could accept 1 or 0 values and it will filter the list of the active offers or used. Response: json Redeem offer (store in user's offers list) ------------------------------ URL: https://licklist.co.uk/offers/redeem.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] - required, integer, id of the offer Response: json Using the redeemed offer ------------------------------ URL: https://licklist.co.uk/redeemables/activate.json (old url)https://licklist.co.uk/offers/using.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] - required, integer, id of the redeemed record (different from offer_id). Should be taken from the list of redeemed offers Response: json View Redeemable ------------------------------ This should be displayed in the screen and the button for activating the offer should be there URL: https://licklist.co.uk/redeemables/view.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] - required, integer, id of the redeemed record Response: json Removing the redeemed offer ------------------------------ This could happen only if the user doesn't used the offer yet URL: https://licklist.co.uk/redeemables/delete.json (old url)https://licklist.co.uk/offers-redeems/delete.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] - required, integer, id of the redeemed record Response: json List user's notifications ------------------------------ The structure of Notifications json is very similar to Status hub/social feed. There are 3 main nodes: Who - this most of the time could be 1 node, but could be more than one (for now just for comments - example "John, Jane and Joe commented on a photo") What - This is the action e.g. Friend, ImageTag, Comment or GoingOut objects Objects - this always should have 1 object underneath, but to be consystent with the Status it's an array of objects Important to note is that some notifications require some interaction with them e.g. Friend request or GoingOut confirmation This state is in the node "action_required". If action is required, 2 buttons need to be placed in the row of notification: Accept or Decline Once the action is taken the "action_required" is set to 2 which mean action is taken. In the node action_response is the text which need to be displayed instead of the buttons if the action_required is 2 URL: https://licklist.co.uk/notifications/index.json Parameters: $_REQUEST['start'] - optional, integer, defaults to 0 - offset Response: json Notification action ------------------------------ This is action call of those notifications, which had action_required eq 1 URL: https://licklist.co.uk/notifications/action.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] - required, integer, id of the notification $_REQUEST['type'] - optional, string, defaults to 'accept'. The parameter accept either 'accept' or 'decline' values Response: json - the response will contain the text should be placed instead of the buttons/links GoingOut Accept invitation ------------------------------ URL: https://licklist.co.uk/going-outs/accept.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] - required, integer, id of the goingout record Response: json Storing User's device token for APSN/GCM ------------------------------ This call need to be done when the device is promoed for push network registration and it register the device. Usually this is happening when User register for the first time from a mobile device. URL: https://licklist.co.uk/users/device.json Header: See "Secondary requests" section for reference Parameters: $_POST['uid'] - required, string id of the device $_POST['type'] - required, string, currently it could accept 2 type of devices 'ios' and 'android' $_POST['token'] - required, string, The token key from the push network. If the token is json object it should be converted to string Response: json User's Social Summary ------------------------------ This call is similar to "User's Hub" call, but here user will see also his friend's events/statuses as well as events/galleries/offers from venues which are in a certain radius from his location. So: Social Summary contain: 1. User's activity (se User's hub section) 2. User's friends activity 3. Events, Offers, Galleries from Venues arround user's location Think of this call like Facebook's news feed which is different of User's profile URL: https://licklist.co.uk/status/summary.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['start'] - optional, integer, offset Response: json Location autocomplete ------------------------------ URL: https://licklist.co.uk/locations/autocomplete.json Parameters: $_REQUEST['q'] - optional, string, search string (it is using beginning of the location like 'Ess' will search for Essex, but won't find 'Shoeburryness') $_REQUEST['type'] - optional, string, it could be either 'county' or 'town' if specified it will show only those results which match the type $_REQUEST['parent_id'], optional, integer, parent id of the record. Could be used to filter towns under specific county Response: json Adding user categorization ------------------------------ User categorization is a way to profile the users. Currently we will ask for their preferred music genre and favourite drinks URL: https://licklist.co.uk/users-categorizations/store.json Header: See "Secondary requests" section for reference Parameters: Case 1: When user insert new category $_POST['data']['Categorization']['name'] - required, string, name of the new category $_POST['data']['Categorization']['type'] - required, string, currently could be 'music' or 'drink' Case 2: When user select/deselect existsing category $_POST['id'] - required, integer, id of the redeemed record Response: json Note: The call accept 2 type of parameters: 1. Categorization is passed by name - this is when the user type in the free text field (adding his own choice) 2. Categorization is passed by id - this is when the user select/deselect categorization from an existing entry The function act as toggle the state, so if the user has the selected category and click on it the request will deselect the category and vice versa Categorization list ------------------------------ *Return categorization categories from specified topic for the user* URL: https://licklist.co.uk/categorizations-objects/prompt.json Header: See "Secondary requests" section for reference Parameters: $_GET['type'] - required, string, possible values are: music, drink, activities Response: json Get User selection ------------------------------ Return a list of user selected categories. The list is ordered by popularity and then by name URL: https://licklist.co.uk/users-categorizations/selected.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['type'] - required, string could be either 'music' or 'drink' Response: json Get Popular entries ------------------------------ Return list of entries most popular over the site URL: https://licklist.co.uk/users-categorizations/popular.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['type'] - required, string could be either 'music' or 'drink' Response: json http://dev.licklist.co.uk/friends/index.json?start=12 Get User's friends ------------------------------ Return list of the friends of the logged user or logged user's friends URL: https://licklist.co.uk/friends/index.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['start'] - optional, integer, offset $_REQUEST['id'] - optional, integer, friend's id Response: json Events Calendar ------------------------------ Return dates and their corresponding events as number. The call will return only dates which had events URL: https://licklist.co.uk/events/calendar.json Parameters: $_REQUEST['year'] - optional, int, year (4 digits) if omitted it will be used current year $_REQUEST['month'] - optional, int, from 01 to 12, if omitted it will be used current month $_REQUEST['lat'] - optional, decimal, user's latitude $_REQUEST['lng'] - optional, decimal, user's longitude $_REQUEST['radius'] - optional, integer, radius distance from the latlng point limiting events within specified radius (in km) $_REQUEST['town_id'] - optional, int, town id (it should be used if latlng is not provided) - filtering $_REQUEST['county_id'] - optional, int, county id (it should be used if latlng is not provided) - filtering Header: None Response: json Note: location, town and county could be omitted, this case the api will search the logged user location, if there is no such it will show national search. Once the date is clicked the call should be like: /search.json?lat={lat}&lng={lng}&radius={radius}&filter[object]=Event&&filter[date]={yyyy-mm-dd} depending what parameters has been passed in the calendar search. E.g. if the lat,lng is omitted, then on the second call they shouln'd be in the call either. Post Message ------------------------------ Posting message could be done in 2 ways: By specifying All participants in the conversation or by specifying the conversation_id URL: https://licklist.co.uk/message/messages/add.json Header: See "Secondary requests" section for reference Parameters: $_POST['data[Message][description]'] - required, string - the text which will be posted $_POST['data[Message][recipients][]'] - optional, integer id of the participating user (participants should be user's friend, otherwise it will error) Recipients could be more than one. This parameter could be omitted if conversation_id has been specified. $_POST['data[Message][conversation_id]'] - optional, integer id of the conversation. The parameter could be omitted if recipients list has been provided. $_POST['data[Message][Photo][file]'] - optional, string url of the uploaded file. The file should be uploaded in separate process (like when user register and need to set his profile image) $_POST['data[Message][Photo][id]'] - optional, integer, id of an existing image from the site. This currently shouldn't be used. Later on there should be ability to "sent image to conversation". Response: json List Messages in a conversation ------------------------------ The messages are ordered by ID desc. So the app should turn the vice versa so oldest should be loaded in top URL: https://licklist.co.uk/message/messages/index.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] - optional, integer conversation id $_REQUEST['start'] - optional, integer, offset $_REQUEST['from'] - optional, integer, id of the last message on the screen. When it's specified, the api will return the remaining messages which has been posted since the last message. $_REQUEST['recipients[]'] - optional, integer id of the users in the conversation. The logged user could be missing in that list. e.g. if you (user_id 46) want to speak with users 1 and 36 then recipients should be [1,36] or [1,36,46] in order to pick the proper conversation. Response: json Note: Either id or recipients[] need to be provided in order to get the messages in the conversation. Delete Message ------------------------------ User should be able to delete only his own messages URL: https://licklist.co.uk/message/messages/delete.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] - required, integer message id Response: json Conversations List ------------------------------ This is the conversations which user participated in. They are ordered by last modified conversation desc (latest treads will be in top) URL: https://licklist.co.uk/message/conversations/index.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['start'] - optional, integer, offset Response: json Note: The response return last message and The autor of it. In the node Users are attached all participants in the current conversation Invite Person to Conversation ------------------------------ This call will add ability to invite more people to an existing conversation URL: https://licklist.co.uk/message/conversations/invite.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] - required, integer id of the conversation $_REQUEST['data[user_id][]'] - optional, integer, id of the invited user. Users should be friends of the logged user Response: json Archive Conversation ------------------------------ By this call the user have ability to archive an conversation and if so he won't receive notifications until he start writing to the tread again. URL: https://licklist.co.uk/message/conversations/archive.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['id'] - optional, integer, id of the conversation. User should participate in the tread of course Response: json Notification Count ------------------------------ Return number of unread notifications and messages URL: http://licklist.co.uk/notifications/notify.json Header: See "Secondary requests" section for reference Response: json Categorization Filter ------------------------------ Return all valid filters as multidimentional object. With this could be build filter form. To construct the filter you need to take the key e.g. venue_dresscode_id and selected ids and pass them as array like: /search.json?filter[music_id][]=1&filter[music_id][]=2&filter[enue_avg_age_id][]=1 URL: https://licklist.co.uk/categorizations/filter.json Response: json Collections index ------------------------------ Return list of collections on the site. The collection is a set of manually selected objects based on some criteria. E.g. Cheaper venues, or Venues which has disco music in specific region URL: https://licklist.co.uk/collections/index.json Parameters: $_REQUEST['start'] - optional, integer - defaults to 0, this is the offset of the list. increment that parameter with the number of results on the screen in order to get next result set. The records contain collection details + up to 3 Collection items in it. Collections view ------------------------------ Return data for the single collecion URL: https://licklist.co.uk/collections/view.json Parameters: $_REQUEST['id'] - required, integer - id of the collection. Response: json Collection Items list ------------------------------ This will return items under specified collection (used to make pagination of the items under a collection) URL: https://licklist.co.uk/collection-items/index.json Parameters: $_REQUEST['id'] - required, integer - id of the collection. $_REQUEST['start'] - optional, integer - defaults to 0, offset of the list User Purchased Photos ------------------------------ This will return the list of photos purchased from the logged user. URL: https://licklist.co.uk/payment/orders/uploads.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['start'] - optional, integer - defaults to 0, offset of the list Response: json Terms & conditions ------------------------------ This will return any page by given identifier URL: https://licklist.co.uk/page.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['identifier'] - required, string - any valid page slug (e.g. terms) Notes: For terms & conditions: https://licklist.co.uk/page.json?identifier=terms User Licked Photos ------------------------------ This will return the list of photos purchased from the logged user. URL: https://licklist.co.uk/licks/index.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['start'] - optional, integer - defaults to 0, offset of the list $_REQUEST['object_type'] - required, string - set the object type which you want to see, defaulted to "Upload" Response: json User Change Password ------------------------------ This will return the list of photos purchased from the logged user. URL: https://licklist.co.uk/users/password.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['password_old'] - required, string - old password of the user $_REQUEST['password'] - required, string - new password of the user Response: json New terms and condition and consent of messages ------------------------------ The endpoint should be called if the user's toc attribute is 0. This mean that the user need to accept licklist's new terms and conditions. Along with terms and conditions the endpoint will accept also promotions_licklist and promotions_venues parameters which will get user's consent to send messages to him. If the url is called by GET it will return terms and conditions text as html, so make sure either you strip the tags or use rich container which understand html syntax. The terms and conditions are formated only as plain html tags without any styling in it If the url is called by POST request it will attempt to store the data of the fields toc, promotions_licklist and promotions_venues. It's good if the checkboxes for the promotions_licklist and promotions_venues are false-positive e.g. if unchecked it's true if checked they are 0. See how it's implemented on the registration page of the site also make sure that if the user accepted any of the parameters you don't display it as an option. The promotions_licklist and promotions_venues are available in the user's data after login. URL: https://licklist.co.uk/users/terms.json Header: See "Secondary requests" section for reference Parameters: data[User][promotions_licklist] = 1|0 data[User][promotions_venues] = 1|0 Response: json Membership subscribe ------------------------------ The url should be called when the user is logged in URL: https://licklist.co.uk/membership/membership/subscribe.json Header: See "Secondary requests" section for reference Parameters: token - optional, string - The token should be passed only as id e.g. tok_1CQAVQFGxROSjMgWO1i00s2q The token could be skipped, if the user already has a payment cart assigned to it's profile. You could find this in the user's login data There is a section Payment->Cart which has 4 symbols, if this node exists, means that we have the card assigned. Response: json Membership unsubscribe ------------------------------ The url should be called if the user want to unsubscribe from themembership program. When the user unsubscribe, he will remain member until the current subscription is over e.g. if the user subscribe today, and unsubscribe 10 days later, he will stay a member until the end of the month and then he wont be able to redeem drinks. URL: https://licklist.co.uk/membership/membership/unsubscribe.json Header: See "Secondary requests" section for reference Parameters: none Response: json Membership redeem drink ------------------------------ The url should be used for the app to redeem a drink from the venue. If the url is accessed via _GET it will return whether the user can redeem the drink and if not the cause of the failure, but it wont attempt to store it. if the url is accessed with _POST it will attempt to save the redeem attempt if successfull and it will return true or false in the success and error message URL: https://licklist.co.uk/membership/membership/redeem.json Header: See "Secondary requests" section for reference Parameters: $_REQUEST['venue_id'] - required, integer - id of the venue $_REQUEST['drink_id'] - optional, integer - id of the drink if there is a drink selector