restful apis and resource definitions for higher education cifer api

RESTFUL APIS AND RESOURCE DEFINITIONS FOR HIGHER EDUCATIONCIFER API WORK AND THE TIER PROGRAM

Keith HazeltonSr. IT Architect, University of Wisconsin-Madison

Benn OshrinThe Spherical Cow Group

© 2015 Internet2

[ 2 ]

First there was CIFER• Bottom up approach to the problem set that TIER is now taking up in a top-down approach

• CIFER Shared API Team is one of the longer-term active bodies in CIFER

• Team developed a number of artifacts, some of which Benn Oshrin will mention in the second part of this presentation

• As TIER work ramps up, the CIFER API Team will provide TIER – With a set of foundational deliverables– With an initial conceptual model to frame the work to come

[ 3 ]

In TIER-speak, ‘API’ is used as a shorthand reference covering REST-ful APIs, Standard Protocols, Messaging and SDKs

• A partial list of interface/integration approaches that TIER will have to support

© 2015 Internet2

CAS SAML 2

ID Match SCIM 2

LDAP SQL

Oauth 2 UMA

OIDC VOOT 2

ORCID *MQ

[ 4 ]

CIFER Restful API Guidelines• Looking for developer-friendly ways to promote the use of CIFER/TIER guidelines

• And ways to support DRY (Don’t Repeat Yourself) and reuse principles (Two sides of the same coin)

• For RESTful APIs, tools from the likes of raml.org, swagger.io and others help

• E.g. RAML’s API Designer and other tools (components are Apache 2 or CPAL-1.0 licensed) include– Design tool– Documentation tool– Mock-up tool for testing– Code gen tool

© 2015 Internet2

[ 5 ]

Considering use of raml.org tools for API design and documentation

• With RAML you define patterns using traits, resourceTypes and securitySchemes, and then use them as building blocks for an API

• These can be published on the web and then ‘included’ in specific API definitions

• Promotes both DRY and Reuse principles (again)

• Done right, they should save developers both time and effort

[ 6 ]

Data Structures (aka Resource Representations, aka Schema)

• Information objects as canonical representations of entities (People, Groups, Courses, etc.) that should be meaningful across IT systems and vertical domains

• In REST this corresponds to standardized Resource Representations

• Same resources are referenced in event-driven messaging patterns

• We argue that the representations should be congruent and compatible across APIs and message bodies

• DRY and Reuse principles at play here, too

© 2015 Internet2

[ 7 ]

Data Structures (aka Resource Representations, aka Schema)

• Considering advocating JSON for canonical representations

• JSON Schema describes the syntactic structure of a JSON document

• JSON-LD give JSON messages a well-defined meaning by mapping most things to IRIs

• You can use them together.

© 2015 Internet2

[ 8 ]

DSAWGThe TIER Data Structures and APIs Working Group

• Credit to BennO, Jim Fox, Chris Hyzer, Jimmy Vuccolo and many others for contributions to the CIFER API work

• Hopefully they will continue to contribute via this new TIER Working Group

• At institutional level, Clemson, U Florida, U Illinois and UW-Madison have already expressed interest in contributing to TIER API work going forward

• Announcements of group creation, invitation to participate to come, track it here:

• https://spaces.internet2.edu/display/DSAWG/TIER-Data+Structures+and+APIs+Working+Group+Home

[ 9 ]

CIFER APIs•More Mature

�(Core Schema)�ID Match�SOR to Registry�Authorization

© 2015 Internet2

[ 10 ]

CIFER APIs•Less Mature

�Registry Extraction�Credential Management

•Not Even Itemized�Management�Monitoring

© 2015 Internet2

[ 12 ]

Use Cases•Intra-Component

�Person Registry queries Group Registry for authorization�Group Registry receives Person Subject records from Person Registry�Person Registry queries ID Match service on new SOR Person record

•Enterprise to Component�System of Record provisions student or employee data to Person Registry

•Enterprise APIs�Home grown Person Registry exposes Person data to campus applications

© 2015 Internet2

[ 13 ]

#TODO•API Documents

�Turn More Mature APIs into Reference Documents or Standards�Turn Less Mature APIs into More Mature APIs�Start Work on Non-Itemized APIs

•Implementations�Reference Implementations�TIER Components (Shib, Grouper, COmanage)�Non-TIER Components (CAS, other IdM projects/products?)

© 2015 Internet2