Skip to content

Funnel API

Jump to bottom Edit New page
Aravind edited this page Oct 14, 2016 · 4 revisions

Funnel API

This is a REST API.

Contents

  • Endpoint
  • Operations
  • Funnel API resources
  • Generic models

Endpoint

https://api.talkfunnel.com/1/

Operations

Each API endpoint supports the following operations (using the users resource as an example):

  • GET /«resource»/«resouce id» Retrieves a single JSON object by id.

  • GET /«resource»?«query» Retrieves a JSON array of objects matching the query. The query is in querystring format, with the following supported arguments:

    • «name of indexed field»=«filter_value»
    • expand=«comma separated names of relations»
    • limit=«integer»
    • order=«name of range indexed field»[,{asc|desc}]

  • GET /«resource»/«resource id»/«relation»?query Retrieves a JSON array of objects through a named relation, for examples to get the participants of an event.

  • PUT /«resource»/«resource id» Create or update an object. Request data should be a full resource object, the semantics should not allow partial updates. Updates will fail unless the PUT version_id matches the latest version.

  • DELETE /«resource»/«resource id» Delete an object.

  • POST /«resource»/«action» Custom actions that don't fit anywhere else, like merging two users. If an action does not neatly fall under a resource, it can be under the root resource.

Resources

First, there are models of venues that are more or less permanent.

Venue/venues

  • location_id

Room/rooms

  • venue_id
  • capacity

Next, there are models of the conference brands, and their annual editions.

Brand

  • brand_id
  • images : Map of urls with keys 'logo', 'cover', etc.
  • colors : Map of hex colors with keys 'background', 'text', 'accent', etc.
  • website
  • admin_team_id
  • labels

Cover is previously the background image.

Edition

  • brand_id
  • sale_id
  • review_team_id
  • images
  • colors
  • website
  • labels

Event

An event is the smallest unit of the conference that an attendee can buy a ticket to — say Day 1 of a particular edition, or a workshop. In legacy code this is referred to as a ProposalSpace.

  • brand_id
  • edition_id
  • inventory_item_id
  • capacity
  • title
  • tagline
  • description : Markdown
  • start
  • end
  • venue_id

Proposal

  • event_id
  • proposer_id → user.id
  • presenter_id → user.id
  • title
  • description : Markdown
  • links : Map of keywords to URLs
  • status
  • vote_target_id
  • comment_target_id
  • labels

Notes:

  • Technical level, Session type, Proposal Space sections can be moved to labels.
  • Objective, Description and Requirements are combined into body.
  • Slides and preview video are in links.
  • Email, phone, location and bio will be retrieved from the user table.

Slot

Slots are the smallest unit of scheduling, and can be a 'presentation' or a 'break'. Room ID is optional, if it is omitted it is assumed to be venue-wide. Presentations are linked to a proposal, but also have a copy of its title, description etc. to allow event organizers to edit the schedule without affecting the underlying proposal.

  • event_id
  • room_id
  • type
  • start
  • end
  • proposal_id
  • presenter_id
  • title
  • description
  • labels

Slot types can be 'presentation' or 'break'.

User

  • username
  • fullname
  • tagline : Usually "«job_title» at «company»".
  • external_ids : Map of strings with keys like 'email', 'phone' and 'twitter'.
  • external_id_claims
  • location_id
  • bio : Markdown

Attendance

This tracks access control, whether the user has a ticket and a badge to the edition of the event. Ideally, the email that BoxOffice sends should contain a form that submits to funnel and creates these.

  • user_id
  • edition_id
  • order_item_id
  • sale_item_id
  • type : 'attendee', 'speaker', 'sponsor', etc
  • badge : Json object with keys like 'pubkey', 'privkey', 'printed'

Presence

This is similar to a session ID for the physical world; events that we log for the user — ContactExchanges, Checkins, Beacon reads,

  • user_id
  • event_id
  • log_id

ContactExchange

If this is only used for logging purposes, I suggest moving this into the generic log.

  • presence_id
  • inviter_id → user.id
  • invitee_id → user.id

FeedbackForm

  • event_id
  • feedback_form_version

FeedbackTarget

  • title
  • type
  • slot_id
  • feedback_form_id

Feedback

  • feedback_form_id
  • feedback_target_id
  • user_id
  • value
  • comment

Generic models

These resources are used by Funnel but are designed to work with a variety of apps.

VoteTarget

Vote

  • vote_target
  • value

CommentTarget

Comment

LabelSet

  • name
  • title
  • multiple

Examples: Topic, ProgrammingLanguage, TechnicalLevel, PresentationType.

LabelValue

  • name
  • title
  • label_set_id

LabelTarget

  • entity_type_id

When an entity that accepts labels is created, the entity type is added to the newly created LabelTarget.

EntityType

EntityTypeLabelSet

Represents restrictions on which LabelSets are applicable to each EntityType.

  • entity_type_id
  • label_set_id
  • required

Label

  • label_set_id
  • label_target_id
  • label_value_id

Locations

This is the table with GeoNames data from the HasGeek API.

Log

This table is just for creating unique IDs; actual data is in the log_line resource.

LogLine

  • log_id
  • type
  • time
  • source : android app, web site, twitter etc.
  • data
Add a custom footer
Add a custom sidebar
Clone this wiki locally