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

[  11 ]

Non-­CIFER  APIs  /  Protocols  of  Interest•CAS•LDAP•OAuth2•OIDC•ORCID•SAML2•SCIM•VOOT2

©  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

[  14 ]

Questions?

benno@sphericalcowgroup.comkeith.hazelton@wisc.edu

©  2015   Internet2