# OSCAL REST API Meeting 20220325

(**NOTE**: Thanks to David Aderton, James Harmison, and Wendell Piez for their notes. They were used to enhance this published copy.)

- Ray Gauss (EasyDynamics) presented [their teams initial draft version of an OSCAL REST API](https://github.com/EasyDynamics/oscal-rest/).
- SSPs can be quite large (10s of MB in definitions)
- OSCAL designed for the document-centric world
- REST API would enable us to programmatically work with documents in small pieces, iteratively and interactively
- Example: Define a person in an application, tie that person reference to all the places where it applies. Generate an OSCAL document with the rendered person, compliant with standard, but doesn’t require repetition.
- Simple CRUD implementation would work for monolithic implementations
- But building a standard REST format to enable this more programmatic interaction enables better support for ecosystem
- Currently using references to EasyDynamics forks of OSCAL schemas, will point to NIST schemas when they accept updates for ref by path support
- UUIDs expected to be globally unique, ideally some System of Record maintains identifiers for shared references across documents (**NOTE: Review this and frame for current meetings in this group and other avenues of discussion in OSCAL community**)
- Any system hosting an application based on this API design would _need_ to maintain uniqueness, because that uniqueness is used to identify objects independent of documents in order to reference attributes.
- Lack of clarity around context for who might host some shared system of record for that. Outstanding question for a future time. Related more to implementation than design.
- For the current REST API for SSPs, a UUID for a party for example will be consistenly unique _across any OSCAL document in the system implementing the REST API and its data store._
- Dave indicated that OSCAL design and documentation talks about consistency in documents this requirement is currently consistent with OSCAL as designed and implemented today.
- Comments and questions from Ray's initial presentation:
- What would be the purpose of a system implementing this?
- Ray's response: Interactive work with OSCAL documents. For example, SAR is updated on the fly with live CI/CD pipeline via a POST.
- When/will we support assessment plan and assessment results model? Strong interest after community consensus on this initial approach.
- Aaron Lippold: this looks suitable for my purposes and should work well with automatic generation of command-line utilities.
- Vicky Deliwala: what standardization we will have in error codes?
- Is this REST API intended for system of record and how will data relationships be persisted? (Not sure how to frame Anca's question)
- David Aderton asked: is the choice of an OpenAPI going to force only JSON as the only response format? What will happen to XML and YAML?
- Dmitry asked if we will have a canonical representation of an object retrieved (by UUID)? Wendell also expressed interest regarding how to address this issue re whitespace sensitivity and data noramlization be handled for uniquely and consistenly identifed documents? (**NOTE: Review this in a subsequent meeting and/or elsewhere for OSCAL community**)
- Questions to answer?
1. Is the Easy Dynamics REST API [1] a good starting point for this effort?
- Hugh - The API includes top level objects and paths to specific leaf items, but there are separate use cases for both. Top-level objects may be easier to standardize.
- While the Easy Dynamics REST API has varying granularity, it may still be a good starting point.
- Vikas - Concern around how frequently the schema would need to change in order to keep up with NIST OSCAL definition
- Anca - Have tried to build a functional API around OSCAL documents before, and struggled to be able to keep the data model useful. Serialization/deserialization has worked fine, but more complex use cases caused some amount of tangle. Concern about mating evolution between clients and servers. Look into work on Trestle ( https://github.com/IBM/compliance-trestle & https://github.com/IBM/compliance-trestle-demos ). What is the use case for OSCAL REST API?
- Ray - Mentions GraphQL, which is not adopted because REST is more prevalent. GraphQL is nicer for searching.
- David W: Future use cases may lead to a combination of GraphQL additions to the REST API
2. What work needs to be done to get an OSCAL content REST API to a useful point for community use?
- Thinking about usage patterns and use cases, better understand the problem space
- Look at alternative specs possibly from Trestle (all models are already in Pydantic internally)
3. How and when should we work together as a community to do this work?
- Lots of interest, ~10ish people
- NIST lacks the bandwidth to advance this alone
- Ray looking for PRs/issues on repository, does not want to maintain themselves
- Looking to host more tactical meetings going forward
4. Is there interest from the OSCAL community in contributing to the effort of standardizing an OSCAL content REST API?
- Seems to be - many on the call interested
- Anca - interested in joining Trestle & EasyDynamics / OSCAL REST API