ZeeDo

ZeeDo

Welcome to the our ZeeDo API documentation. To document and hold API documentation we will use this apiary.io 
service. apiary.io can act as a mock-server or proxy to the real server. It also support comments to each request if any 
if any of them needs improvement or fix. I am very open to provide any further information to mobile app team during development

Please contact me direct: jakub.kuchar@hotmail.com, skype: jakub.chorosh


General introduction to ZeeDo API:

1. All requests needs following 2 headers in order to have response successfully:

  Content-Type: application/json
  Accept: application/json

2. As response following header will be always present (CORS compatible):

  Content-Type: application/json
  Access-Control-Allow-Origin = '*' //wildcard for development purposes will be exact when project is live
  Access-Control-Allow-Methods = 'GET,OPTIONS,PUT,POST,DELETE'
  Access-Control-Allow-Headers = 'Access-Control-Max-Age, Access-Control-Allow-Origin, Origin, Accept, Content-Type, X-Requested-With X-CSRF-Token'
  Access-Control-Max-Age = '1728000'

2.5. If there will be pre-flight check OPTIONS method API will response with 200 and following headers

  Content-Type: text/plain
  Access-Control-Allow-Origin = '*' //wildcard for development purposes will be exact when project is live
  Access-Control-Allow-Methods = 'GET,OPTIONS,PUT,POST,DELETE'
  Access-Control-Allow-Headers = 'Access-Control-Max-Age, Access-Control-Allow-Origin, Origin, Accept, Content-Type, X-Requested-With X-CSRF-Token'
  Access-Control-Max-Age = '1728000'


3. Response's statuses could be in following 
  
  200, 201 - used for successful request
  
  401 - used for authentication required
  
  403 - used for access denied for example GET games/1/snapshots can only access game creator or supervisor
  
  404 - used for if requested resource is not found for example GET users/666
  
  500 - used for standard error - response is with more details in body - example when creating game title must be unique

4. Authentication, sign-up-in

  Authentication is through token and email which have to supplied in every request to API namespace(except index - GET users
  listing). Application is not creating session to store info about logged user. Token for user is created when user is successfully signed-up      and it is permanent and thus same token can be used for any future requests. Token and email are in response body when user is signed-in-up. To    sign-up several method can be used: facebook,twitter,linkedin or standard method with email and password. 
  
  Paragraph above might be subject to change and application could start creating logged-in sessions.

  As you know the first-time sign-up using facebook/twitter/linked-in there is redirection to facebook page to confirm permsision for zeedo facebook app. Hitting /users/auth/facebook will perform this redirect.

If facebook/twitter/linkedin?target=http://www.google.com parameter is supplied it wont respond with json but perform redirect to target as follows
http://www.google.com?jakub.kuchar@hotmail.com&token=n39LfDoFAphEyrZJ6LPx

5. User roles - permissions

  If user using facebook sign-up and he is listed as admin in facebook app, after sing-up he gain brand role.

5. Example workflow simplified version - see requests below for required parameters in requests

5.1 Sing Up brand user

  GET /users/auth/facebook
  -> redirection to facebook page -> token and email as response

If facebook/twitter/linkedin?target=http://www.google.com parameter is supplied it wont respond with json but perform redirect to target as follows
http://www.google.com?jakub.kuchar@hotmail.com&token=n39LfDoFAphEyrZJ6LPx

5.2 Create Game

  POST /api/games?email=brand@brandland.com&token=4GUAzFyEBhZwZ_ds9UZU

5.3 Sing up player via standard method

  POST /users 
  -> token and email as response

5.4 Game listing for player

  GET /api/games/list?email=player@playland.com&token=token&type=available

5.5 Join Game

  POST /api/playgrounds?email=player@playland.com&token=token

5.6 Upload photo to game

  POST api/playgrounds/6/snapshot?email=player@playland.com&token=token

  (recognized attribute in post params can be set true if supplied from mobile)

  If snapshot is recognized and target snapshots of game matched player will have playgounds set as completed

5.7 If snapshot is NOT recognized - game creator can set it as recongized manually

  GET api/snapshots/58/recognize?email=brand@brandland.com&token=4GUAzFyEBhZwZ_ds9UZU

5.8 Game creator can suspend/sleep the game and no one will join or upload photo

  GET api/games/3/sleep?email=brand@brandland.com&token=4GUAzFyEBhZwZ_ds9UZU