I Know Let's Make an API - Samvera Connect 2019

Owned by Jeremy Friesen
Oct 25, 2019
2 min read

Let's Build an API

Facilitator: Adam Wead
Timekeeper: Kate Lynch
Notetaker: Jeremy Friesen

Idea of Samvera centered around Rails architecture, but our technical realities are shifting and moving.

Thesis: What would it take to define Samvera as a set of one or more API sepcs?

We want an API so that we can decouple front-end APIs. We want an API so that we can decouple with our language and data stores.

There exists an emerging API in front of Hyku (Brian Hole is workign on it).

Penn State is moving forward with an API Spec for Sufia: https://psu-stewardship.github.io/scholarsphere-api

Our applications are using Blacklight.
Back in the day we looked into the PCDM API. Challenges of "how do I make this in one transaction?" And found challenges addressing the specific implementations for organization. An emerging moment in 2016, was these specificiations began looking like a Fedora 4 JSON API.

Are we thinking about a REST API? Is [GraphQL](https://graphql.org) something to consider? GraphQL has one end-point, where you can query one data shape and update one data shape. Drawbacks of GraphQL: It's easy to get yourself in a place where someone can take your server away. It does not mimic HTTP spec. GraphQL is a projection of your data model. Recommendation from GraphQL is don't build CRUD APIs, but build interactions.

Can we share a data model? Are there pieces of the stack that communicate with other elements of the stack? There is a lot of fragility in micro-services.

If Hyrax had a GraphQL API, people could build against that. Looking for separation of components. See cues from UCS(B|D)'s Surfliner. Would some APIs reduce the amount of magic of what is going on? Poking the stack is a lot of opacity. A very large chunk of opacity is the ActorStack, if the error that you got came from an end-point instead of somewhere within a deep context nested set of functions.

Discussion about Valkyrie: ROM was a strong consideration, but we wanted to make quick and weird storage adapters. But a Fedora adapter was hard.

Have we had a working group for Samvera data models? Would this working group be a good place to start? Would it be reasonable to hash out a data model. We do have Data model PCDM with FileSet extension. Figgy has FileMetadata as an extension. This is due to Valkyrie implementation.

Concern regarding API against a data model instead of API against actions/transactions. The API's point should hide the complexity from the client. Blacklight is now exposing a JSON API end-point. A call to migrate Hyrax to Blacklight.

Actions:

  • Who has a GraphQL implementation? How can we share and test-drive against those?
    • Princeton
    • Northwestern (exists but pending "public" status)
    • Penn State (in-progress)
  • Who has interaction APIs defined: 
    • Notre Dame
    • Stanford
    • Northwestern
  • Look to refinement of the ActorStack
    • Could this be spec-ed out? Could the jagged edges be filed away? Could we make an adapter? This is a key customization point, a ChangeSet.
    • Delegate this to the Tech Call
  • Request for feedback on Valkyrie on how to comprehend, also
    • Jeremy F - plans to spend 4 hours in the next 2 weeks
  • Revisit and update Samvera model, that extends PCDM data model (with FileSet and FileMetadata)
    • Esmé will create a draft and circulate