Resistance Calendar API

API for Resistance Calendar events

Getting Started

Prerequisites

• MongoDB from the downloads page
• Node Package Manager

Demo

An instance of the application is running at the following location:

https://resistance-calendar.herokuapp.com/v1/events

Endpoints

All endpoints try to be compliant with the OSDI Events standard which exposes two high level endpoints and a few options for paging:

• https://resistance-calendar.herokuapp.com/v1/events
• https://resistance-calendar.herokuapp.com/v1/events/{:id}
• https://resistance-calendar.herokuapp.com/v1/events?page=0&per_page=25

Queries

Queries are intended to comply with the ODATA standard and use odata-v4-mongodb to do so which implements much, but not all of the standard. Some examples of common queries are:

Start date

Filter by start date (dates in ISO8601 format):

• https://resistance-calendar.herokuapp.com/v1/events?$filter=start_date gt '2017-03-01'
• https://resistance-calendar.herokuapp.com/v1/events?$filter=start_date gt '2017-03-01' and start_date lt '2017-03-02'

Nested properties

Filter by nested property (postal_code and locality/city):

• https://resistance-calendar.herokuapp.com/v1/events?$filter=location/postal_code eq '22980'
• https://resistance-calendar.herokuapp.com/v1/events?$filter=contains(location/locality, 'Savannah')

Text searching

This can be done via multiple contains functions combined via and / or logical operators and are not case sensitive.

• Require both via and:
• https://resistance-calendar.herokuapp.com/v1/events?$filter=contains(name, 'Sessions') and contains(name, 'Fire')
• Require any via or:
• https://resistance-calendar.herokuapp.com/v1/events?$filter=contains(name, 'Sessions') or contains(name, 'DeVos')

Location

Searching is not technically ODATA compliant since there is not affordance for radial searches. This implementation filters by location using coordinates (longitude, latitude), city, or postal code and distance in meters. If coordinates are specified, they are used as they are the preferred method of location based searching since postal_codes are only supported for US and may be out of date.

• http://resistance-calendar.herokuapp.com/v1/events?distance_coords=[-98.435508,29.516496]&distance_max=10000
• http://resistance-calendar.herokuapp.com/v1/events?distance_postal_code=94110&distance_max=10000
• http://resistance-calendar.herokuapp.com/v1/events?distance_city=Albuquerque&distance_max=10000

Ordering

Again, using the ODATA standard, ordering is done like so:

• Single field sort: http://resistance-calendar.herokuapp.com/v1/events?$orderby=start_date
• Multi field sort: http://resistance-calendar.herokuapp.com/v1/events?$orderby=start_date asc
• Ascending (the default): http://resistance-calendar.herokuapp.com/v1/events?$orderby=start_date asc
• Descending: http://resistance-calendar.herokuapp.com/v1/events?$orderby=start_date,title desc

Cities endpoint

Intended to find the city based on a set of coordinates

• http://resistance-calendar.herokuapp.com/v1/events?distance_coords=[-98.435508,29.516496]&distance_max=10000
• Sample response:
• {"zipcode":"78217","state_abbr":"TX","latitude":"29.543865","longitude":"-98.41755","city":"San Antonio","state":"Texas","distance":3.504331766837608}

Created / updated at queries

For ETL based processes, limiting the number of events queried for can be done by created_date and modified_date fields

• https://resistance-calendar.herokuapp.com/v1/events?$filter=created_date gt '2017-03-01'
• https://resistance-calendar.herokuapp.com/v1/events?$filter=created_date gt '2017-03-01'&orderby=created_date

Run the server

cd resistance-calendar-api

# Export the facebook token. Eventually this can be made to auto-refresh using the app secret.
export FB_GRAPH_API_TOKEN=[YOUR FACEBOOK TOKEN]

# Start mongodb
mkdir .db
mongod --dbpath .db/

# Always a good idea to install packages
npm install && npm install semistandard -g

# Run the tests!
npm test

# Run the service
npm start

Technical Architecture

The service is a node service based on the hapijs framework and uses mongodb