when getting api_user from auth_token:
    if an AuthToken with auth_token=params[:auth_token] is found:
      if that auth_token is linked to an existing ApiUser:
        # note: we had an existing auth_token with an existing api_user
        return auth_token.api_user

      else
        search for an ApiUser with api_key=auth_token.apikey, user=@current_user, device=nil, device_version=nil, app_version=nil:

        if found:
          # note: we have a legacy AuthToken that has yet to be associated with its corresponding legacy ApiUser
          associate auth_token with this api_user
          return auth_token.api_user

        else
          # note: we have a legacy AuthToken that never had an associated legacy ApiUser
          create a new ApiUser with api_key=auth_token.apikey, user=@current_user, device=nil, device_version=nil, app_version=nil:
          associate auth_token with this api_user
          return auth_token.api_user

    else:
      # note: login failed or whatever
      return nil


when getting auth_token from api_user:
    if api_user.auth_token is nil:
      if api_user.device==nil, api_user.device_version==nil, and api_user.app_version==nil:
        search for an AuthToken with apikey=apikey and user=user and api_user=nil

        if found:
          # note: we have a legacy ApiUser that had yet to be associated with its legacy AuthToken
          associate auth_token with api_user
          return api_user.auth_token

        else:
          # note: we have a legacy ApiUser that never had an associated legacy AuthToken
          create a new AuthToken with apikey=auth_token.api_key, user=api_user.user
          associate auth_token with api_user
          return api_user.auth_token

      else:
        # note: we have a non-legacy api_user that has yet to have an AuthToken generated for it
        create a new AuthToken with apikey=auth_token.api_key, user=api_user.user
        associate auth_token with api_user
        return api_user.auth_token

    else
      # note: we have an existing ApiUser that had an existing AuthToken
      return api_user.auth_token