Miami Open 211 API (HSDA)

This is a portal for the Miami Open 211 API (HSDA) implementation. It provides data access to the human services data stored in the database, and allows for building of applications on top of the API.

All read (GET) APIs are publicly available, while being able to add (POST), update (POST), and delete (DELETE) data from the system requires authentication using a valid Github account. All transactions are record via the HSDA meta system, providing a log of everything that occurs using HSDA Meta.

You will find instructions below for getting started, authenticating, interactive documentation, and support.

Getting Started

There are six separate microservices contained as part of this Human Services Data API (HSDA) work. HSDA is the core service, focusing on the management of organizations, locations, services, contacts, and their sub-resources (ie. addresses, phones, etc.). The other seven microservices are meant to be standalone services that augment the core HSDA service.

Here is a quick list of the eight services, which there are separate documentation available below:

HSDA Full - The core service for managing organizations, locations, services, contacts, and other sub-resouces in single API calls.
HSDA Detailed - The core service for managing organizations, locations, services, contacts, and other sub-resouces.
HSDA Search - A spin-off search service from the core service, focusing exclusively on searching across HSDA resources.
HSDA Taxonomy - An independent service for managng taxonomy used by the core set of services. It uses Open Elgibility currently.
HSDA Meta - An independent service for recording all transactions executed via any HSDA implementation, providing comprehensive logging.
HSDA Management - The simple API management layer for HSDA, leveraging Github authentication to be able to make calls to HSDA APIs.

To get started I recommend beginning with authentication which will get you an API key allowing you to make calls across all services, not just the public GET resources. Then spend time with the interactive documentation for each service to better understand how they work independently, but also in concert with each other. It is meant to provide a buffet of HSDA services that work together, operate independently, and can be moved forward as separate projects.

Authentication

This implementation of HSDA leverages Github as the authentication layer for the API. Most of the GET API paths are open to the public, but any POST, PUT, DELETE, and management level APIs require an appid and appkey to accompay each request as headers.

Click on the Github logo to authentice using your Github account. The OAuth flow will take you back to this portal, adding you to the HSDA Management layer, showing you what your access keys will be. Each API call will have to contain:

x-appid - Your Github user.
x-appkey - Your Github token.

The HSDA Management service will validate your appid and appkey as being a valid Github account and token, then give access to make calls to all API paths, across all services. Invalid API requests will receive a 403 status code for any API requests.

Any valid Github user and token will work with the API, you do not need to login via the portal every time you are looking to get access for any future applications.

Base URL:

This is the base URL for the Miami Open 211 API, which you can use as the base to make calls to the API.

http://miami.open.211.hsda.api.adopta.agency/

The documentation below will allow you make live API calls to the API, but the base URL will get you going.

Human Services Data API (HSDA) Full (v1.2)

This is the interactive documentation for the core set of Human Services Data API (HSDA) resources. If you are looking to get a full responses for all core resources, as well as their sub-resources in a single API call, these are the paths for you. These four endpoints will return full responses for each resource in a single response.

This set of paths are intended to be about working with core resouces (ie. organizations, locations, contacts and services), there are other spearate HSDA services that give you access to a variety of systems that support, augment, and work with the core set of Human Services Data API (HSDA) services.

Support

There are three ways that you can get support when using this API--consider one of the following channels when you have a question, comment, or some feedback regarding the API and integration.

Github

Twitter

It is recommended that you start with submitting a Github issue, then maybe tweet at us. If your questions or comments require some privacy you should use email. Make sure you look through the existing issues before submitting a new one.