exafox / ohana-api

The open source API directory of community social services.

#Ohana API

This is the API portion of the Ohana API project, an open source community resource platform developed by @monfresh, @spara, and @anselmbradford during their Code for America Fellowship in 2013, in partnership with San Mateo County's Human Services Agency. The goal of the project is to make it easier for residents in need to find services they are eligible for.

Before we started working on the Ohana API, the search interface that residents and social workers in San Mateo County had access to was the Peninsula Library System's CIP portal. As a demonstration of the kind of applications that can be built on top of the Ohana API, we developed a better search interface (repo link) that consumes the API via our Ruby wrapper. We also built an admin site to allow organizations to update their own information.

We encourage third-party developers to build additional applications on top of the API, such as this SMS-based search interface that Mark Silverberg started developing. You can register your app on our developer portal (branding work in progress), and view the API documentation.

Current Status

We are happy to announce that this project has been awarded a grant from the Knight Foundation, which means we get to keep working on it in 2014! Our primary goals this year are: simplifying the installation process, streamlining the code, reducing dependencies, and preparing the project for broader installation by a variety of organizations and governments.

One of the major changes will be replacing MongoDB and Elasticsearch with Postgres. This work will probably begin between mid-March and mid-April.

Data Schema

We are working on documenting the current schema and data dictionary, but please note that this will be in flux as we are working with various interested parties to define a Human Services Data Specification.

In the meantime, you can browse the 3 main models: Organization, Location, and Service, and see the fields they each have.

A Location also has address, mail_address, and contact attributes, which are defined as separate models (embedded documents in MongoDB).

Taxonomy

We are currently using the Open Eligibility taxonomy to assign Services to Categories. Ohana API only accepts the categories defined by Open Eligibility.

The easiest way to assign categories to a service is to use the Ohana API Admin interface. Here's a screenshot:

You can also try it from the Rails console, mimicking how the API would do it when it receives a PUT request to update a service's categories.

API documentation

http://ohanapi.herokuapp.com/api/docs

Search documentation

Ruby wrapper

https://github.com/codeforamerica/ohanakapa

Apps that are using the Ohana API

SMC-Connect GitHub repo for SMC-Connect

Ohana API Admin site

Ohana SMS

Stack Overview

• Ruby version 2.0.0
• Rails version 3.2.16
• MongoDB with the Mongoid ORM
• Redis
• ElasticSearch
• API framework: Grape
• Testing Frameworks: RSpec, Factory Girl, Capybara

Deploying to Heroku

See the Wiki.

Installation

Please note that the instructions below have only been tested on OS X. If you are running another operating system and run into any issues, feel free to update this README, or open an issue if you are unable to resolve installation issues.

###Prerequisites

Git, Ruby 2.0.0+, Rails 3.2.16+ (+ Homebrew on OS X)

OS X: Set up a dev environment on OS X with Homebrew, Git, RVM, Ruby, and Rails

Windows: Try RailsInstaller, along with some of these tutorials if you get stuck.

MongoDB

OS X

On OS X, the easiest way to install MongoDB (or almost any development tool) is with Homebrew:

brew update
brew install mongodb

Follow the Homebrew instructions for configuring MongoDB and starting it automatically every time you restart your computer. Otherwise, you can launch MongoDB manually in a separate Terminal tab or window with this command:

mongod

MongoDB installation instructions using MacPorts are available on the wiki.

Other

See the Downloads page on mongodb.org for steps to install on other systems: http://www.mongodb.org/downloads

Redis

OS X

On OS X, the easiest way to install Redis is with Homebrew:

brew install redis

Follow the Homebrew instructions if you want Redis to start automatically every time you restart your computer. Otherwise launch Redis manually in a separate Terminal tab or window:

redis-server

Redis installation instructions using MacPorts are available on the wiki.

Other

See the Download page on Redis.io for steps to install on other systems: http://redis.io/download

ElasticSearch

OS X

On OS X, the easiest way to install ElasticSearch is with Homebrew:

brew install elasticsearch

Follow the Homebrew instructions to launch ElasticSearch.

Other

Visit the Download page on elasticsearch.org for steps to install on other systems: http://www.elasticsearch.org/download/

Clone the app on your local machine:

From the Terminal, navigate to the directory into which you'd like to create a copy of the Ohana API source code. For instance, on OS X cd ~ will place you in your home directory. Next download this repository into your working directory with:

git clone git://github.com/codeforamerica/ohana-api.git
cd ohana-api

Install the dependencies and prepare the DB:

script/bootstrap

Note: Installation and preparation can take several minutes to complete!

If you get a permission denied message, set the correct permissions:

chmod -R 755 script

then run script/bootstrap again.

In config/application.yml, set the ADMIN_APP_TOKEN environment variable so that the tests can pass, and so you can run the Ohana API Admin app locally:

ADMIN_APP_TOKEN: your_token

your_token can be any string you want for testing purposes, but in production, you should use a random string, which you can generate from the command line:

rake secret

Run the app

Start the app locally on port 8080 using Passenger:

passenger start -p 8080

Verify the app is returning JSON

To see all locations, 30 per page:

http://localhost:8080/api/locations

To go the next page (the page parameter works for all API responses):

http://localhost:8080/api/locations?page=2

Search for organizations by keyword and/or location:

http://localhost:8080/api/search?keyword=food
http://localhost:8080/api/search?keyword=counseling&location=94403
http://localhost:8080/api/search?keyword=market&location=san mateo
http://localhost:8080/api/search?location=redwood city, ca

Search for organizations by languages spoken at the location:

http://localhost:8080/api/search?keyword=food&language=spanish

The language parameter can be used alone:

http://localhost:8080/api/search?language=tagalog

Searches with the location parameter return results sorted by distance. Searches with the keyword parameter return results sorted by relevance based on a match between the search term and the organization's keywords field.

Pagination info is available via the following HTTP response headers :

X-Total-Count

X-Total-Pages

X-Current-Page

X-Next-Page

X-Previous-Page

Pagination links are available via the Link header.

Here is an example response using cURL: curl -s -D - http://ohanapi.herokuapp.com/api/search\?keyword\=shelter -o /dev/null

Response Headers:

HTTP/1.1 200 OK
Cache-Control: max-age=0, private, must-revalidate
Content-Type: application/json
Date: Wed, 19 Feb 2014 14:16:40 GMT
Etag: "f104eaabf805bd034a7c376f15b66a4b"
Link: <http://ohanapi.herokuapp.com/api/search?keyword=shelter&page=3>; rel="last", <http://ohanapi.herokuapp.com/api/search?keyword=shelter&page=2>; rel="next"
Server: nginx/1.4.4 + Phusion Passenger 4.0.37
Status: 200 OK
X-Current-Page: 1
X-Next-Page: 2
X-Powered-By: Phusion Passenger 4.0.37
X-Rack-Cache: miss
X-Request-Id: af51fefe-4eee-48a6-8172-f232001976bd
X-Runtime: 0.699663
X-Total-Count: 86
X-Total-Pages: 3
X-Ua-Compatible: IE=Edge,chrome=1
Content-Length: 140193
Connection: keep-alive

If you're a Rubyist, you can access this info easily by using our Ruby wrapper. Check out the Accessing HTTP Responses section of the README.

If you just want to fetch the results for the next page, for example, then you should use the Link headers as opposed to constructing your own URLs based on the other pagination headers. The wrapper makes that easy too:

shelters = Ohanakapa.search("search", keyword: "shelter")
next_page_results = Ohanakapa.last_response.rels[:next].get.data

If you want to append the next page results to the previous results:

shelters = Ohanakapa.search("search", keyword: "shelter")
shelters.concat Ohanakapa.last_response.rels[:next].get.data

Read more about search in the API docs.

Tools

We recommend these tools to interact with APIs:

JSONView A Google Chrome extension for formatting the JSON response so it is easier to read in the browser.

HTTPie command line utility for making interactions with web services from the command line more human friendly.

Resetting the app

If you want to wipe out the local test DB and start from scratch:

script/drop
script/bootstrap

User authentication and emails

The app allows developers to sign up for an account via the home page (http://localhost:8080), but all email addresses need to be verified first. In development, the app sends email via Gmail. If you want to try this email process on your local machine, you need to configure your Gmail username and password by creating a file called application.yml in the config folder, and entering your info like so:

GMAIL_USERNAME: [e-mail]
GMAIL_PASSWORD: your_password

application.yml is ignored in .gitignore, so you don't have to worry about exposing your credentials if you ever push code to GitHub. If you don't care about email interactions, but still want to try out the signed in experience, you can sign in with either of the users whose username and password are stored in db/seeds.rb.

To try out the Rails Admin interface, you need to set the "role" of the admin user to "admin". The easiest way to do this is with a MongoDB GUI like one of these. You can find the admin user in the "admins" collection. Once you've set the role, go to /admin and sign in with the username and password listed in db/seeds.rb.

Test the app

Run tests locally with this simple command:

rspec

For faster tests:

gem install zeus
zeus start #in a separate Terminal window or tab
zeus rspec spec

To see the actual tests, browse through the spec directory.

Drop the database

If you ever want to start from scratch, run script/drop, then script/bootstrap to set everything up again. Do this on your local machine only, not in production!

Contributing

In the spirit of open source software, everyone is encouraged to help improve this project.

Here are some ways you can contribute:

• by using alpha, beta, and prerelease versions
• by reporting bugs
• by suggesting new features
• by suggesting labels for our issues
• by writing or editing documentation
• by writing specifications
• by writing code (no patch is too small: fix typos, add comments, clean up inconsistent whitespace)
• by refactoring code
• by closing issues
• by reviewing patches
• financially

Submitting an Issue

We use the GitHub issue tracker to track bugs and features. Before submitting a bug report or feature request, check to make sure it hasn't already been submitted. When submitting a bug report, please include a Gist that includes a stack trace and any details that may be necessary to reproduce the bug, including your gem version, Ruby version, and operating system. Ideally, a bug report should include a pull request with failing specs.

Submitting a Pull Request

1. Fork the repository.
2. Create a topic branch.
3. Add specs for your unimplemented feature or bug fix.
4. Run rspec. If your specs pass, return to step 3. In the spirit of Test-Driven Development, you want to write a failing test first, then implement the feature or bug fix to make the test pass.
5. Implement your feature or bug fix.
6. Run rspec. If your specs fail, return to step 5.
7. Run metric_fu -r. This will go through all the files in the app and analyze the code quality and check for things like trailing whitespaces and hard tabs. When it's done, it will open a page in your browser with the results. Click on Cane and Rails Best Practices to check for files containing trailing whitespaces and hard tabs. If you use Sublime Text 2, you can use the TrailingSpaces plugin to highlight the trailing whitespaces and delete them. If the report complains about "hard tabs" in a file, change your indentation to spaces by clicking on Tabs: 2 at the bottom of your Sublime Text 2 window, then selecting Convert Indentation to Spaces. As for the code itself, we try to follow GitHub's Ruby styleguide.
8. Add, commit, and push your changes.
9. Submit a pull request.

Copyright

Copyright (c) 2013 Code for America. See LICENSE for details.