RESTful APIs Toward a common Design

Developers from several projects have worked together for over a year to converge on a shared framework for RESTful API design. Work is underway to implement APIs according to that framework in the Apereo Open Registry Project, Penn State's Central Person Registry and Grouper. A number of institutions are also following those guidelines in APIs developed for local use. This session will provide an overview of the framework, walk through example cases and show how it eases the tasks of developers working with these APIs. While the original arena of application has been identity and access management, the presenters will make the case that participants would benefit from adopting the API design framework in additional contexts.

Transcript

1. RESTful APIs: Toward a Common Design (The CIFER Shared API Working Group) Open Apereo June 3, 2014 Keith Hazelton UW-Madison, InCommon/I2
2. Topics • Why Develop a Framework for RESTful APIs • Framework V1 Walk-Through • Case Studies—Framework-Aligning APIs • SCIM vis-à-vis the CIFER API Framework • “Resources” across APIs, Notifications and Messages
3. The Worker Bees • CIFER Shared API Working Group • Includes key developers from a number of open source Identity and Access Management (IAM) projects • Working together for a year and a half now • Jointly developed a RESTful API Framework • Applying the Framework in their respective projects – Jim Fox, U of Washington; Keith Hazelton, UW-Madison, Chris Hyzer, U Penn; Benn Oshrin, SCG; Brian Savage, Boston U; Bill Thompson, Unicon; Jimmy Vuccolo, Penn State U
4. IAM as interconnected services
5. Why APIs, Why RESTful? • Key design goals for IAM infrastructure – Modular services – Loose coupling between services and their consumers • Interface is just a word for the inter-service connection points • APIs as live, published representations of interfaces • RESTful APIs: Showing up across domains, across project and products
6. RESTful – Beyond the Buzz • Leverages the ubiquitous HTTP protocol • And the Standard HTTP methods/verbs • A focus on Resources identified by HTTP urls • And on CRUD operations on those resources via HTTP methods • Yields loose coupling – Clients and Services can be implemented in language of choice – Clients and Services are location agnostic (cloud, anyone?)
7. http://ciferproject.org/sites/default/files/ciferproject-org- framework-api-v1-draft-02.html • A collaboratively developed standard the Shared API WG participants agree to follow when developing/evolving their service-specific APIs • The beneficiaries are first and foremost the client-side developers who work with multiple such services – Learn once, apply to many projects CIFER API Framework 01 ciferproject-org-framework-api-v1-draft-02
8. CIFER API Framework 2. Definitions RESTful This framework references Representational State Transfer (REST), where a service is composed of an addressable set of resources. URIs are used to address resources and transitions of a resources state are accomplished by direct, stateless client interactions with these URIs. Clients of the service may: • Search for resources, • Get a representation of a resource, • Add or replace a resource, and • Delete a resource
9. CIFER API Framework 5.1 Grammar and Format Constraints 5.1.1 URI Syntax A major version of a particular CIFER API must be indicated in the URI path (for example, "/v2/”) A major version will differentiate incompatible representations, parameters or headers. A major version change is also triggered by a change in field type. Any minor version will be indicated in the response metadata not in the URI path (see response section below)
10. CIFER API Framework 5.1.3 Data and field formats 1. Character set is Unicode, encoded as UTF-8 2. Timestamp representations will comply with ISO 8601. For example: 2012-10-04T03:10:14.123Z 3. Durations also comply with ISO 8601, For example: P1.81S
11. CIFER API Framework 5.1.3 Data and field formats… 4. Field names are camelCase (including acronyms), e.g. "selfUri” 5. Where there is discretion enum and other fixed field values should be camelCase 6. Field names must start with a letter. They can contain upper/lower letters, numbers and underscores 7. Field types must stay consistent within a major version 8. Objects are identified by uri – For example: netId:mchyzer, or userId:12345678 – {scheme name}:{hierarchical part}
12. CIFER API Framework 5.2.2. Request methods 1. The request method of POST may be overridden by a header (see header options below) … 5.2.2. Header Options 1. The request method of POST may be overridden by the header: 1. X-HTTP-Method-Override: GET | PUT | DELETE (When, e.g., there is a request body required in a GET)
13. Framework-aligned APIs • Open Source Identity Registries – Penn State Central Person Registry (CPR) – Apereo Open Registry • First version of the Framework was defined before CPR RESTful APIs • CPR design adopted and aligned with the Framework • APIs Documented on the CPR Design Wiki • https://wikispaces.psu.edu/display/IdSExternal/CPR+RE STful+Service+Model
14. Central Person Registry APIs Service URI Method Add a person /v1/people POST Update a person /v1/people/identifier-type:identifier PUT Archive a person /v1/people/identifier-type:identifier DELETE Get a person /v1/people/identifier-type:identifier GET
15. CPR API: Add person POST /v1/people { "attributes": { "updatedBy":"xyz123", "gender":"M", "dob":"1990-01-01", "name":{ "nameType":"LEGAL_NAME", "firstName":"James", "lastName":"Smith" }, "address":{ "addressType":"PERMANENT_ADDRESS", "address1":"121 Hill Road", "city":"Some City", "stateOrProvince":"PA", "countryCode":"USA" }, "phone":{ "phoneType":"PERMANENT_PHONE", "phoneNumber":"814-111-1212" }, … }
16. CPR API: Add person Success: New person created; response code “201: Created” { "resource":{ "personId":"121234", "userid":"xyz123", "psuId":"912345678", "uri":"/v1/people/121234" }, "resourceMetadata": { "lastModified":"2012-10-04T03:10:14.123Z", "baseUri":", "statusCode":"SUCCESS!" }, "responseMetadata": { "responseTimestamp:"2012-10-04T03:10:14.123Z", "responseTime":"2", "httpStatusCode":"201", "serverVersion":"1.0" } }
17. • Framework Section 5.4.2 Response codes – 200: the resource was found – 201: the resource was created – 400: the request was not valid – 401: the client was unauthenticated – 403: an authenticated client was not authorized for the request – 404: a requested resource was not found – 409: (conflict) • PUT to an existing resource without an If-Match – 412: (precondition failed) • If-Match header did not match resource's ETag, or • If-Match header supplied but resource not found (add with an if- match), or wildcard if-match not allowed – 500: server error CPR API: Add person
18. CPR API: Add/Delete affiliation Add: POST /v1/people/identifierType:identifier/affiliations { "attributes": { "updatedBy":"xyz123", "affiliation":"STUDENT" } } Returns an “affiliation key” that uniquely identifies the added affiliation value “Archive”: /v1/people/identifierType:identifier/affiliations/affiliationKey DELETE /v1/people/personId:121234/affiliations/112112?requestedBy=xyz123
19. Framework-aligned APIs • ID Match API (Benn Oshrin’s presentation yesterday) • When a System of Record (HR, Student, other) sends identity information for a person new to them, how do you determine if that is about someone already known to the Identity Registry? • ID Match as a generic service that can be plugged to identity registry of choice – CPR – Open Registry – …
20. • CPR was developed before ID Match API was complete • So the current CPR version has its own built-in ID matching functionality • POST of a person that’s new to the calling SOR but that CPR recognizes as potential match is indicated in response codes: – 200 OK: Single exact match found – 300 Multiple choices: More than one existing CPR resource matches the POSTed values • A full ID Match API implementation would offer a much richer set of functionality at the cost of some code and process refactoring CPR and ID Match
21. • Grouper (group and permission management services) • Grouper’s REST-ish web services predate the CIFER Shared API working group • Grouper developer will tweak the APIs to produce a set that is aligned with the framework • Get members of a group – GET /grouper- ws/servicesRest/json/v2_2_000/groups/aStem%3AaGroup/mem bers • Get all groups to which a particular person belongs – GET /grouper- ws/servicesRest/json/v2_1_001/subjects/10021368/membership Grouper RESTful APIs
22. Grouper RESTful APIs • APIs cover a rich set of resources and actions on them: – Groups – “Stems” (folders for groups) – Members (people or groups) – Attributes – Privileges (over Groups and Stems) – Permissions (over arbitrary resources)
23. SCIM vis-à-vis CIFER Framework • System for Cross-domain Identity Management (SCIM) – http://www.simplecloud.info/ • Version 2 under active development under IETF WG • Design center: Provisioning users and groups to external services • Current draft specification for SCIM’s RESTful API – http://tools.ietf.org/html/draft-ietf-scim-api-05
24. SCIM vis-à-vis CIFER Framework • Do we need both SCIM and the CIFER API Framework? • Potential alignment point: SCIM’s support for custom schema extensions • SCIM doesn’t cover all the CIFER resources (see Grouper resource list above) • SCIM isn’t suited to natively handling multiple roles with associated attribute graphs (a la Apereo Open Registry) • But given potential for vendor adoption, we will likely need to provide the SCIM variants of our APIs for people (aka SCIM “users”) and groups – SCIM API spec authors from Oracle, Salesforce, Cisco, Sailpoint
25. Restful APIs and change event notifications • Both can deal with resources in the RESTful sense • So why not represent them in a consistent fashion • Again, the developer of clients would be the beneficiary
26. • Notification proposal on the Shared API site – Simplest model: message IDs resource, recipient must retrieve and process - PUSH message to a messaging endpoint: PUT /v1/events/<service>/<serialnumber> { "serialNumber":103, "entity":"/v1/people/enterprise/49873", "timestamp":"2012-10-04T03:10:14.123" } Restful APIs and change event notifications
27. Change event notifications • Notification proposal on the Shared API site - Client PULLs change messages from the registry: GET /v1/events?since=<serialnumber> 200 OK { "events": [ { "serialNumber":103, "entity":"/v1/people/enterprise/49873", "timestamp":"2012-10-04T03:10:14.123Z" }, { "serialNumber":104, "entity":"/v1/people/enterprise/49873", "timestamp":"2012-10-04T03:10:19.100Z" } ] }
28. Restful APIs and change event notifications • Grouper-to-LDAP provisioning at U Washington, CPR event messages – Message can indicate type of change, resource URI and perhaps the resource itself – Very early days for this line of thinking
29. Conclusion • Shared API WG focus has been around people and groups because they predominate in the domain of identity and access management • If your service has IAM integration points, this work might be of direct benefit • The model and conventions should be applicable to other domains and to multiple types of non-person resources • Subscribe to the CIFER API list at https://lists.internet2.edu/sympa/subscribe/cifer-api