API updates

updates.txt

A few general notes:
  * We switched from Mongo to Postgres, so all the lookups are ID based rather than filename/foldername based.
  * There's a new table "photo_sequence".  The hierarchy is "folder 1->* photo_sequence 1->* upload", where a "sequence" denotes e.g. one run through the gif sequence, and the corresponding "uploads" are each of the individual phots, gifs, user-edits, etc from that sequence.
  * Folders can contain multiple "galleries", each of which has its own sharing configuration.  A common use case is in printer mode, they'll have one gallery for the individual shots allowing social, and one for the composites just allowing prints, and run two separate tablets.
  * The workflow for customizing images and forms has been improved, allowing things like gif annotation without custom code.
  * I denote an array of objects below by brackets, e.g. [string] is a string array or [{id:int;name:string}] is an array of that record type.
  * ... means there are other fields you can ignore
  * v4 api servers: api.smilebooth.com, api-test.smilebooth.com
  * v4 web servers: admin.smilebooth.com, admin-test.smilebooth.com (these are just for you manually to configure folders; your app should always hit the API server)
  * (v4 test and prod are currently the same)
  * smileport: port 20003

/api/v4/user/get-by-login-info
  Input: 
      { username: string
        password: string }
  Output:
      { token: string
        ... }
  Description: You'll need this for direct-to-cloud connections.  The only field you need is "token", which you'll need to add to the "x-user-token" header in all subsequent API posts.
  


/api/v4/folders/list-names
  Description: Returns all folders user has access to, or in offline mode returns all folders on smileport.  (There's no longer a need for a portal selection step; this endpoint returns all folders in all portals that user has access to)
  Input: none
  Output:
    [ { id: int
        name: string } ]

  
/api/v4/folders/get-sharing-details
  Description: Returns all galleries in that folder.  Each gallery has its own name, id, and sharing configuration.  Prompt the user to choose a gallery, and use the corresponding info onward in the app.
  Input:
    { id: int } (the id of the folder selected above)
  Output:
    { folder: { ... }
      galleries: 
        [ { id: int
            name: string
            tablet:                     
              { customThemeEnable: bool
                customThemeUrl: string
                printEnable: bool
                aviaryEnable: bool
                useFormstack: bool
                formstackUrl: string
                customOverlaysEnable: bool
                customOverlayUrls: [ string ]
                customBackgroundUrls: [ string ]
                ... }
            form: 
              { enable: bool
                termsOfService: string
                requireOptIn: bool
                requireOptInDefaultChecked: bool
                optInText: string
                askName: bool
                askZip: bool
                askBirthday: bool
                customFields: [ string ]
                useProcessingScript: bool }
            email: 
              { enable: bool
                ... }
            mms: 
              { enable: bool
                ... }
            twitter: 
              { enable: bool
                tweet: string
                ... }
            ... } ] }
  Notes:
    * Oauth is dead on tablets, so no more facebook and twitter is handled differently (see below)
    * form.customFields is a list of custom field names|labels to append to the form.  i.e. if there's an entry "mood|How Are You?" you'd append a textbox with label "How Are You?", and submit the answer as "mood" in the JSON when you call the sharing endpoints (see those below for more details).
    * form.useProcessingScript described below in upload-apply-script
    * We allow any combo of customization/workflow options to be enabled in a gallery.  Then on the tablet they're done one at a time in the order [background->aviary->overlay->form->formstack] before showing the sharing buttons.
  

/api/v4/images/list-by-gallery
  Description: Gets all the photos by gallery.
  Input:
      { galleryId: int
        since: int64 }
  Output: 
    [ { id: int64
        sequenceId: int64
        url: string
        thumbUrl: string
        ... } ]
  Notes:
    * sequenceId is a key to denote "related" photos.  So e.g. when you do the Aviary workflow, you'd upload the user-edited version with the same sequenceId as the original.
  

/api/v4/images/get
  Description: Gets a single photo by id
  Input: int64 (the id)
  Output: 
      { id: int64
        sequenceId: int64
        url: string
        thumbUrl: string
        ... }
  Notes:
    * this is used for displaying the results of "upload-apply-script" and other server-side photo processing results detailed below.


/api/v4/sequences/create
  Description: Creates a new sequenceId.
  Input:
      { folderId: int
        mode: int
        source: string }
  Output: int (the id)
  Notes:
    * On tablets, this is only needed for the "Local Directory Watcher" feature -- for each new photo you'd first create a new sequenceId and then upload using that id (see upload-* endpoint)
    * "mode" should always be zero, meaning "clicker mode", in tablet directory watcher workflows; source can be "iPad".
    * All other tablet functionality you're modifying an existing image, so you'd reuse the same sequenceId.
    

/api/v4/images/upload
  Description: Uploads a photo.
  Input: MULTIPART
    "info" :
      { sequenceId: int64
        subtype: int
        position: int }
    "media": the bytes.
  Output: int64 (the id)
  Notes:
    * Only used in directory watcher scenario.
    * Ensure filename is included in the "media" section.
    * "subtype" should always be zero, meaning "original", and "position" should always be zero, meaning "first" (it's used for gif frames).
    * "sequenceId" should be the return value of the "sequences/create" call you perform immediately prior to this step.
    
    
/api/v4/images/upload-user-edit
  Description: Uploads a user-edited photo (aviary)
  Input: MULTIPART
    "info" : { sequenceId: int64 }
    "media" the bytes.
  Output: int64 (the id)
  Notes:
    * sequenceId should match that of the original photo
    * Only used in aviary scenario.
    * Ensure filename is included in the "media" section.
  

/api/v4/images/upload-apply-overlay
  Description: Uploads a custom overlay/background photo
  Input: MULTIPART
    "info" : { sequenceId: int64 }
    "background" the bytes of the background image.
    "overlay" the bytes of the overlay image (presumably a png file).
  Output: int64 (the id)
  Notes:
    * sequenceId should match that of the original photo
    * So for custom overlays you'd set the original image to "background" and the chosen overlay to "overlay"; for custom backgrounds you'd set the background to "background" and the keyed original png to "overlay".
    * This means you don't have to process the photo on the tablet (in Android it made things easier because I could just have a static background and a slider on top for the user to select overlay).
    * It also means you can do it with gifs and videos.
    * Then to get the URL of the resulting photo, you call "images/get" with the returned id from here.


/api/v4/images/upload-apply-script
  Description: Applies an imagemagick script to an image
  Input: MULTIPART
    "info" :
      { sequenceId: int64
        galleryId: int }
    "args" :
      { firstName: string 
        lastName: string
        ...: string
        ...: string }
    "media" the bytes.
  Output: int64 (the id)
  Notes:
    * You use this after the user fills out a form and form.useProcessingScript is set.
    * It sends the photo along with all the form data (in "args") to an imagemagick script that will be running, so it can e.g. watermark your photo with your name for instance.
    * (Combined with the custom form fields feature, it allows you to set up all kinds of stuff like gif annotation without needing special software)
    * sequenceId should match that of the original photo
    * galleryId should be your current gallery


    
*** The below are all sharing, with similar structures ***
  /api/v4/sharers/email/share
    Input:
      { uploadId: int64
        galleryId: int
        email: string
        formData: string }
  /api/v4/sharers/mms/share
    Input:
      { uploadId: int64
        galleryId: int
        phone: string
        formData: string }
  /api/v4/sharers/twitter/share
    Input:
      { uploadId: int64
        galleryId: int
        username: string
        formData: string }
    Notes:
      * Twitter now just tweets from the @smilebooth account, appending @username to the tweet so the user receives it without needing to go through oauth.
      * Usually we'll have it use twitter cards to point to our web galleries, which has all the standard social sharing links, to make resharing on other platforms easier and safer.  Nobody trusted oauth.
  /api/v4/sharers/print/share
    Input:
      { uploadId: int64 }
  Outputs: int64 (the new record ID - you can ignore it)
  Notes:
    * formData is a JSON-encoded string rather than being an actual sub-object here.