EasyDynamics / oscal-rest

An initial OpenAPI definition of an OSCAL REST API.
Creative Commons Attribution Share Alike 4.0 International
38 stars 13 forks source link

Refactor REST API Specification (BASIC) #70

Closed brian-comply0 closed 1 year ago

brian-comply0 commented 1 year ago

User Story

As a developer of OSCAL-enabled tools, I want a REST API specification that - when implemented as a service - enables me to view and manipulate OSCAL files contained within any organization's repository with this specification implemented.

Acceptance Criteria

Background

With increased understanding of OSCAL within the team, and a more refined understanding of how entities will interact with OSCAL content, we need to revise the REST API specification such that it more completely addresses the user story above.

This includes, but is not limited to:

brian-comply0 commented 1 year ago

March 27, 2023 - Team discussion:

brian-comply0 commented 1 year ago

March 27, 2023 - Team Discussion

Clean up spec to clarify the use of oAuth2 tokens within the header of API calls.

NOTE: The implementation will handle the connection between an oAuth2 token and an identity as well as the access rights of that identity.

brian-comply0 commented 1 year ago

From March 22, 2023 - Team Discussion

Handling of versions:

Bronstrom commented 1 year ago

4/7/23 Sprint Planning - Moved from Sprint 44 to Sprint 45

tuckerzp commented 1 year ago

Pushing to Sprint 46

brian-comply0 commented 1 year ago

We worked on the following yesterday:

When Valid 200 Return 201 Return 400
Bad Request
401
Unauthorized
403
Forbidden
404
Not Found
409
Conflict
410
Gone
415
Unsupported Media Type
422
Unprocessable Content
GET Any endpoint X Object X X X X X
PUT Any endpoint X Object X Object, Location Header X X X X X X X X
DELETE Any endpoint, where cardinality is not exactly 1 X Object X X X X X
PATCH Any endpoint that can unambigulously point to a single object X Object X X X X X X X X
POST Any endpoint that can unambiguously point to a single object X Object, Location Header X X X X X X X X
brian-comply0 commented 1 year ago
We updated the above guidance as follows: Node Cardinality Node's ID/UUID Cardinality Description Template
GET by identifier
(1 object returned)
n/a 0 [Not possible - do not generate]
GET by identifier
(1 object returned)
n/a 0 or 1 When ["an id" | "a uuid"] is available, returns the [node name] represented by the identifier.
GET by identifier
(1 object returned)
n/a 1 Returns the [node name] represented by the identifier.
GET no identifier
(1 or more objects returned)
n/a n/a Returns every relevant [node name].
PUT n/a 0 [Not possible - do not generate]
PUT n/a 0 or 1 When ["an id" | "a uuid"] is available, updates the [node name] specified by the identifier, and returns the updated [node name].
PUT n/a 1 Updates the [node name] specified by the identifier.
DELETE exactly 1 n/a [Not allowed - do not generate]
DELETE other than exactly 1 0 [Not possible - do not generate]
DELETE other than exactly 1 0 or 1 When ["an id" | "a uuid"] is available, deletes the [node name] specified by the identifier.
DELETE other than exactly 1 1 Deletes the [node name] specified by the identifier.
PATCH n/a 0 [Not possible - do not generate]
PATCH n/a 0 or 1 When ["an id" | "a uuid"] is available, updates the [node name] specified by the identifier.
PATCH n/a 1 Updates the [node name] specified by the identifier.
POST 0 or 1 n/a When a [node name] does not exist, adds a new [node name].
POST exactly 1 n/a [Not allowed - do not generate]
POST 0/1 or more n/a Adds a new [node name].

NOTES:

and broke the return codes out into a separate table: 200 Return 201 Return 400
Bad Request
401
Unauthorized
403
Forbidden
404
Not Found
409
Conflict
410
Gone
415
Unsupported Media Type
422
Unprocessable Content
GET X Object X X X X X
PUT X Object X Object, Location Header X X X X X X X X
DELETE X Object X X X X X
PATCH X Object X X X X X X X X
POST X Object, Location Header X X X X X X X X
mpemy commented 1 year ago

@brian-easyd Thanks for posting these updates here.

brian-comply0 commented 1 year ago

@mpemy - As discussed, this issue is morphing into "OSCAL REST API Basic" and focuses on file-level operations. A separate issue will be created for "OSCAL REST API Complete" with the more detailed operations.

For every model, we should have:

PRIMARY

SNAPSHOTS

ATTACHMENTS

PROFILE RESOLUTION For Profiles, we also need to handle resolved profiles. In addition the above, Profile endpoints include:

Bronstrom commented 1 year ago

6/8/23 Sprint Planning - Moved from Sprint 48 to Sprint 49

Bronstrom commented 1 year ago

6/22/23 Sprint Planning - Moved from Sprint 49 to Sprint 50

Bronstrom commented 1 year ago

7/6/23 Sprint Planning - Moved from Sprint 50 to Sprint 51

brian-comply0 commented 1 year ago

July 6 and 10 review and feedback notes

API Review:

Kyle's chat notes:

PUT - use 204 No Content https://swagger.io/docs/specification/describing-responses/#headers

PATCH - Use 200 and return the document for the "level" where the request was made.

PATCH /catalog/{catalogId} should return the full catalog regardless of what fields were included in the response. PATCH /catalog/metadata/parties/{partyId} would return the entire modified party (note not the catalog) regardless of what field was modified. If the client needs the UUID/last-modified, they can GET for the full document

Brian's note: PATCH /catalog/metadata/parties/{partyId} is not part of the basic spec. This will be relevant in the complete spec later.

GET /catalog/{catalogId}/attachment

This should return an object with:

{
  "attachment-list": [
    {
      "id": "string",
      "media-type": "string",
       "name": "string"
    }
  ]
}

GET /catalog/{catalogId}/attachment/{attachmentId}

We may need to, for OpenAPI reasons, specify the content type as application/octet-stream however we should CLEARLY AND THOROUGHLY document that it will be variable based on the specified media type and that octet-stream is the FALLBACK

brian-comply0 commented 1 year ago

REST API Review - July 26, 2023