slavingia / osdi-docs Goto Github PK

The Open Supporter Data Interface (OSDI) effort seeks to define an API and data structures for interoperability among products in the progressive cause-based, campaign and non-profit marketplace. The existence of a common API will reduce customer costs related to moving data between different systems, lower integration costs and enhance the ability of innovators to create products for the marketplace.

OSDI membership is made up of progressive vendors and organizations as well as invited non-partisan and mainstream industry vendors.

More Information about OSDI can be found at: opensupporter.org

The Github source for these documents can be found at: https://github.com/opensupporter/osdi-docs

If you are looking at those sources now and want to see the prettier github pages version, look here: https://opensupporter.github.io/osdi-docs

Experiment with our prototype server: http://api.opensupporter.org

• API Overview and Structure
  • Version
  • Working with OSDI in Real Life
  • REST + HAL
  • Versioning
  • Helpers
  • API Entry Point and Linking
  • Curies
  • Collections and Navigation
  • Filtering Collections
  • Encryption
  • Authentication
  • Mime Types
  • Error Handling
  • Flexibility and Server Behavior
  • Deviations from RESTful Behavior
  • Common Fields
  • Notational Conventions
• References
• Authors and Leadership
• Contributing and Contact

OSDI used a combination of approaches to provide flexible reading of data, simple operations for simple scenarios, and general purpose CRUD access.

This document represents OSDI version 1.1.2

OSDI Servers SHOULD expose the HAL Browser to provide a consistent interface for developers, scripters, digital, tech and data staff to work with.

In the course of writing scripts, reports, applications and other utilities that integrate via OSDI, examining and inspecting the different resources available on a server is a significant component of time spent. By having a consistent interface to work in, customers can further decrease their costs.

Ask your OSDI vendor for the URL to their HAL Browser.

An OSDI jQuery plugin has been created for use with OSDI's non-authenticated POST feature. The plugin facilitates a javascript implementation of OSDI, allowing for HTML forms to POST data into an OSDI system using AJAX in a user's browser, all without much coding.

Learn more about the plugin and download a copy here.

Generally, OSDI follows traditional RESTful practices for accessing resources and collections of resources as well as creating, editing, updating, and deleting resources.

OSDI also implements the JSON+HAL spec hypermedia standard, providing links to associated collections and resources. JSON+HAL specifies a simple way to embed linking into APIs. The combination of linking and a specification allows generic clients to be written and, indeed, many languages have HAL clients. Linking itself makes it easier to both reason about and write clients for an API.

By default, server responses should expand first level instances unless otherwise specified. For example, in a response for a collection of resources, those resources should be embedded.

Finally, OSDI implements the OData query language for filtering collections.

Back to top...

OSDI uses Semantic Versioning. In practice, this means:

• Breaking changes will use a new major version number (eg: 2.0)
• New features will use a minor version number (eg: 1.1)
• Incremental Bug fixes may use a sub-minor version number (1.1.1)

When accessing a server, a client can determine the OSDI version by examining the osdi_version attribute in the API Entry Point (AEP).

Back to top...

OSDI also allows a client to perform a number of operations at once that in a traditionally RESTful API would take multiple requests through the use of helpers. For example, helpers can be used to create a new Person resource and register that this new person also signed a petition at the same time, something that with REST would require two operations (first creating the person, then associating them with the petition).

Back to top...

All access through OSDI starts at the API Entry Point (AEP). The AEP is a resource that acts like a directory of the types of resources available on a server. It also includes capability information like the maximum query pagesize and links to helper endpoints.

Your service provider can tell you what the AEP URL is for your account.

You can explore the AEP with a user-friendly interface by visiting our prototype endpoint.

Back to top...

You may have noticed that most links are prefaced with a name space "osdi" and that in the _links section there is a key labeled "curies." The link section defines links to relationships between objects and curies define those relationships. You will find documentation on the particular relationship by using the templated curie link. For example, given the following links section:

"_links": {
    "curies": [{ "name": "osdi", "href": "http://api.opensupporter.org/docs/v1/{rel}", "templated": true }],
    "self": {
        "href": "http://api.opensupporter.org/api/v1/answers/46"
    },
    "osdi:question": {
        "href": "http://api.opensupporter.org/api/v1/questions"
    }
}

In order to fetch documentation on the question relationship, you would visit the following url: http://api.opensupporter.org/docs/v1/question

Any links not prefaced with a curie name space are defined here.

Vendors who add their own vendor-specific relationships must defined their own curie and preface their relationships with their own curie namespace. For example,

"_links": {
    "curies": [
        { "name": "osdi", "href": "http://api.opensupporter.org/docs/v1/{rel}", "templated": true },
        { "name": "fb", "href": "http://facebook.com/docs/v1/{rel}", "templated": true }
    ],
    "self": {
        "href": "http://api.opensupporter.org/api/v1/question_answers/46"
    },
    "osdi:question": {
        "href": "http://api.opensupporter.org/api/v1/questions"
    },
    "fb:profile": {
        href: "http://facebook.com/profiles/1234"
    }
}

Back to top...

When retrieving collections, the response representation will include some common attributes.

Collection responses may include additional links for navigation to previous and next pages.

The parameters per_page and page control pagination.

• ?per_page specifies how many results to return per page.
• ?page specifies the starting page to start with.

Back to top...

When retrieving collections, a client may request that the server filter the results according to a query. OSDI makes use of a subset of the OData query language to accomplish this. The filter string is the value of the 'filter' query parameter.

See OData Filter Query for more information.

General information can be found at odata.org.

• String literals are enclosed in single quotes, eg: 'Jon'
• Integers are not quoted, eg: 5
• The whole query string is not enclosed in any quotes

OSDI supports the following OData operators:

OSDI defines the following OPTIONAL extension operators:

OSDI defines the following OPTIONAL extension functions:

Find all males in a given ZIP code: GET /api/v1/people?filter=gender eq 'Male' and address.postal_code eq '10011'

Find new signups on or since a date and time (Eastern Time) GET /api/v1/people?filter=created ge '2013-11-17T18:27:35-05'

Back to top...

Providers should support secure HTTPS connections using TLS 1.0 and above, and reject non-secure HTTP connections.

If necessary, providers may support non-secure HTTP connections in addition or instead.

Back to top...

Clients and providers may use a variety of mechanisms to authenticate and authorize operations. The specification does not currently require supporting a specific method. However, there are many choices which can work with this specification.

• Cookie-Based Authentication
• HTTP Basic
• HTTP Digest
• Token-Based Authentication
• OAuth and OAuth 2.0
• OpenID

Future versions of this specification may officially support one or more of these methods, or provide standard ways of implementing various methods, or may in other ways be more specific about security and authentication.

Not all interactions with the API will require authentication, and some behaviors might differ based on whether your request includes authentication or not. For example, when used in a javascript application, where authentication secrets can't be kept from users, a non-authenticated method may be used, and the server response may be truncated so as to not leak data to unauthenticated users. Some specific non-authenticated behaviors included in this specification are outlined on each resource page.

While OSDI does not currently mandate implementation of token-based authentication, for those that do implement this method of authentication the following standard should be followed.

For header-based token authentication, the header should be named OSDI-API-Token (case sensitive), as in this example:

OSDI-API-Token: [your token here]

For URL query string-based token authentication, the query parameter should be named osdi-api-token (case insensitive), as in this example:

https://api.opensupporter.org/api/v1/?osdi-api-token=[your token here]

Back to top...

When sending requests or responses, the preferred mime type is application/json.

Servers and clients are strongly encouraged to be liberal in accepting entities with a missing or incorrect mime type.

Back to top...

If the attempt to access, update, or create the a resource or collection fails, the server shall return the appropriate HTTP error code representing the failure.

Within the response body, the server shall include descriptive information on the nature of the failure.

Back to top...

Not all systems that implement OSDI will implement all aspects of the specification.

There are no required fields in OSDI, and many relations are left up to each individual system and server.

Some servers may support some or all of the different resource collections. For example, a peer to peer donation system might support Donations and People but not events. In order to find out what resources are available and what URIs to use to access them, do a GET on the AEP URL.

Some servers may support certain helpers and not others. The AEP and associated resources also includes links to the helper endpoints available.

Similarly, matching behavior will be determined by each implementing system. For example, some systems may match people based on email address or other information.

This section outlines areas where the expectations of the OSDI customer community differ from boilerplate RESTful behavior and specify best practice expected behavior.

Numerous resources in OSDI contain embedded objects (hashes) and arrays. For example, on Person, Birthday and Custom Fields are Objects (hashes) and Postal Addresses is an array.

When dealing with updates to these elements of resources, servers should merge rather than replace these elements. This is more consistent with expected user behavior. This relates to helpers and POST's to collections.

For example, sending a person_signup_helper, or a POST on the person collection with only 1 address should not delete any existing addresses. Similarly, including only 1 custom field, should not delete all existing custom fields on a resource.

The behavior for PUT is currently unspecified and up to server behavior. Contact your vendor for more details.

In order to cause the deletion of the contents of an Object (hash) or Array, a request should include that element, but set its value to null

Back to top...

All OSDI resources share a set of common fields for consistency. These are listed below.

{% include global_fields.md %}

Back to top...

In this specification, when defining models, the following notational conventions are used.

In the description of string types, sometimes the specification will list a set of acceptable values such as

In these cases, the string value should conform to one of the choices unless specified otherwise.

Back to top...

• Leo Aguayo, Organizer
• Tim Anderegg, New Organizing Institute (NOI)
• Topper Bowers, Independent
• Beth Becker, Indigo Strategies
• Gilbert Chan, Organizer
• Josh Cohen, Washington United For Marriage (Editor)
• Jeff Crigler, Catalist
• Gustavo Costa, The Action Network
• Michael Eskin, Blue State Digital
• Jascha Franklin-Hodge, Blue State Digital
• Abraham Godong, FasterCampaigns
• Tim Gutowski, Trilogy Interactive
• Chuck Hagenbuch, Blue State Digital
• Harlan Hill, Indigo Strategies
• Tim Holahan, BroadStripes
• Matt Klaber, Independent
• Ben Krokower, FasterCampaigns
• Eli Lee, The Quad
• Dave Leichtman, Microsoft Corporation
• Marc Love, Independent
• Walter Ludwig, Indigo Strategies
• Drew Miller, NGP VAN
• Joe McLaughlin, Citizen Action of New York
• Mark Paquette, TheDataBank
• Charles Parsons, Salsa Labs
• Rich Ranallo, Revolution Messaging
• Jason Rosenbaum, The Action Network
• Shaie Sachs, NGP VAN
• Ben Stein, Mobile Commons
• Ben Stroud, Targetsmart Communications
• Ray Suelzer, UFCW International Union
• Nate Thames, ActBlue
• Jim Pugh, ShareProgress
• Sylvia Rolle, Washington United for Marriage
• Chris Thomas, Sierra Club
• Brian Vallelunga, Trilogy Interactive (Editor)
• Sandra Wechsler, The Quad
• Nathan Woodhull, ControlShift Labs
• Ryan Zarkesh
• Misha Zhurkin, Catalist

• Reed Probus, Web, Logo & Graphic Design
• Nathan Tabak, Whitepaper writing and editing
• Anthony Whittaker, Evangelism and Booth Duty
• Scott Wooledge, V1 Logo

See our governance committee members and executive officers.

Back to top...

Anyone is welcome to contribute by filing GitHub issues. To join our committees for specification discussion, please contact us at http://opensupporter.org or via email at [email protected].

Back to top...