Revised Attachment Handling

[brian-comply0]

Description

As a developer issuing OSCAL REST API calls to manage attachments, I want a more seamless integration between the attachment endpoints and the OSCAL content related to those attachments.

Specifically, I want attachment methods and endpoints to address the following:

• The UUID assigned to the back-matter/resource for the attachment must be the identifier used in the REST API endpoints for managing attachments (/{model-name}/{file-id}/attachment/{UUID-of-backmatter-resource}).
• The specification must require the implementation to manage the OSCAL back-matter/resource content as well as the attachment itself.
• The implementation should ensure the rlink/@href value assigned within the back-matter/resource allows API clients to easily make additional GET calls to retrieve the attachment using the resource/rlink/@href value.
  • For example, the implementation should use @href values such as:
  • /attachment/{resource-UUID} (preferred); or
  • https://{api.base.url}/{model-name}/{file-id}/attachment/{uuid-of-attachment}.
• The specification must provide the ability to update the back-matter/resource content associated with an attachment.

---

Acceptance Criteria

• [x] The specification for GET, PUT and DELETE methods involving the /[model-name]/{file-id}/attachment/{attachmentID} endpoint changes {attachmentID} to {resourceUUID}. The revised endpoints should be /[model-name]/{file-id}/attachment/{resourceUUID}

• [x] The specification for POST /[model-name]/{id}/attachment is updated as follows:

  • The description must be updated to to say:
  • "Adds a new attachment and creates a new back-matter resource in the OSCAL file. The UUID of the resource is returned. "
  • The 201 response schema must change the "id" field to "resourceUUID":

    {
    "attachment": {
    "file": {
    "resource-uuid": "string",
    "name": "string",
    "media-type": "string",
    "attachment-binary": "string"
    }
    }
    }

• [x] The specification for DELETE /[model-name]/{file-id}/attachment/{resourceUUID} is updated as follows:

  • The description must be updated to to say:
  • "Deletes the attachment and the associated back-matter resource represented by the resource UUID."

• [x] The specification for PUT /[model-name]/{file-id}/attachment/{resourceUUID} is updated as follows:

  • The description must be updated to to say:
  • "Replaces the attachment represented by the resource UUID"

• [x] A new specification is added for PUT /[model-name]/{file-id}/attachment/{resourceUUID}/resource, which includes:

  • A description that states:
  • "Updates the content of the back-matter resource represented by the resource UUID, consistent with the NIST OSCAL 1.1.2 syntax for back-matter resource assemblies."
  • A JSON payload that matches the syntax of back-matter resource assemblies.
  • Valid return codes should match those used in other PUT methods. (204, 400, etc.)

• [x] A new specification is added for GET /[model-name]/{file-id}/attachment/{resourceUUID}/resource, which includes:

  • A description that states:
  • "Retrieves the content of the back-matter resource represented by the resource UUID, consistent with the NIST OSCAL 1.1.2 syntax for back-matter resource assemblies."
  • Return Information
  • Valid return codes should match those used in other GET methods. (200, 400, etc.)
  • A JSON payload that matches the syntax of back-matter resource assemblies.

---

Concept of Operations (ConOps)

The ConOps is that a client interacting with the REST API is either:

• sending an OSCAL file and all of its attachments; or
• retrieving an OSCAL file, and some or all of its attachments

SENDING OSCAL CONTENT

1. When a client is sending an OSCAL file and attachments, the following steps are used:
   • Client: POST /{model-name}
   • Server: Stores file
   • Server: Assigns {file-id}
   • Server Returns:
   • Response code: 201 (Success - Payload Attached)
   • Payload: { "{model-name}-id" : "{file-id}" }

2a. For each existing attachment that is already defined in the OSCAL file (content already has a back-matter/resource):

• Client: PUT /{model-name}/{file-id}/attachment/{resourceUUID} (optionally includes Content-Type header)
• Server: Stores attachment
• Server: finds back-matter/resource with uuid={resourceUUID} from the endpoint
• Server: OPTIONALLY adds or updates a resource/rlink/@href with a path to the REST API endpoint for the attachment.
  • Server: Sets the above rlink's @media-type to the Content-Type header value if provided)
• Server Returns:
  • Response code: 204 (Success - No Payload Attached) NOTE: Server should ignore and leave in place any rlink with an absolute path or URI fragment in the @href flag.

2b. For any new attachments that are not yet defined in the OSCAL file:

• Client: POST /{model-name}/{file-id}/attachment (optionally includes Content-Type header)
• Server: Stores attachment
• Server: generates UUID value {uuid-of-new-attachment}
• Server: creates new back-matter/resource with `@uuid="{uuid-of-new-attachment}"
• Server: OPTIONALLY adds resource/rlink:
  • sets the @href flag to /attachment/{uuid-of-attachment}
  • sets the @media-type to the Content-Type header value if provided)
• Server Returns:
  • Response code: 201 (Success - Payload Attached)
  • Payload: { "resource-uuid" : "{uuid-of-back-new-attachment}" }

3. For either of the attachment methods above, the client can follow the PUT or POST with the following to adjust the content of the back-matter/resource associated with the attachment:
   • Client: PUT /{model-name}/{file-id}/attachment/{resourceUUID}/resource with JSON payload to set or modify the resource's title, description, prop[@name='type'], and other properties and fields as defined in the OSCAL 1.1.2 specification forback-matter/resource`
   • Server: Identifies the back-matter/resource by {resourceUUID}
   • Server: Replaces all resource content with the delivered content.
   • Server Returns:
   • Response code: 204 (Success - No Payload Attached)

RETRIEVING OSCAL CONTENT

1. When a client is retrieving an OSCAL file and attachments, the following steps are used:
   • Client: GET /{model-name}
   • Server: Provides JSON file with list of OSCAL files of that model name, including the {file-id} for each.
   • Client: GET /{model-name}/{file-id}
   • Server: Provides OSCAL file as payload.
   • Client: Processes OSCAL content as needed, identifies an attachment of interest, and notes it's {resourceUUID}
   • Client: Retrieves the attachment using either:
   • A valid and reachable rlink/@href value within the resource; OR
   • GET /{model-name}/{file-id}/attachment/{resourceUUID}
   • Server Returns:
   • Response code: 200 OK
   • Attachment

### Tasks

[brian-comply0]

Made good progress on the collection of issues. This one will be addressed in sprint 68.

[mpemy]

Made good progress. This one will be addressed in sprint 69.

[brian-comply0]

Per today's discussion:

• The description for the resourceUUID parameter should be "UUID of the Back Matter Resource". This applies to:

  • GET /[model-name]/{file-id}/attachment/{resourceUUID}
  • PUT /model-name]/{file-id}/attachment/{resourceUUID}
  • DELETE /[model-name]/{file-id}/attachment/{resourceUUID}
  • GET /[model-name]/{file-id}/attachment/{resourceUUID}/resource
  • PUT /[model-name]/{file-id}/attachment/{resourceUUID}/resource

• The JSON return should match the OSCAL JSON back-matter/resource syntax. This applies to:

  • GET /[model-name]/{file-id}/attachment/{resourceUUID}/resource
  • PUT /[model-name]/{file-id}/attachment/{resourceUUID}/resource
  • POST /[model-name]/{file-id}/attachment This represents a change from above

• The JSON return should be as specified below for the following endpoint:

  • GET /[model-name]/{file-id}/attachment (JSON "attachment" array with 0 or more items)

{
  "attachment-list": [
      {
      "resource-uuid": "string",
      "file-name": "string",
      "media-type": "string",
      "title": "string",
      "published": "19-02-29",
      "version": "",
      "remarks": "string"  
      }
   ]
}

NOTES:

• This represents several changes form the original issue:
  • It changes "attachment" to "attachment-list"
  • It changes "name" to "file-name"
  • It properly shows that "attachment-list" is an array (includes [ and ] in the appropriate location)
• The following field is changed the attachment list as compared to other lists:
  • "resource-uuid" instead of "file-id"
• The following fields appear in the attachment list, but not other lists:
  • file-name
  • media-type
• The following fields appear in other lists, but not the attachment list:
  • "last-modified"
  • "oscal-version"
  • "document-ids"
  • "markings"

[pjavan]

@mpemy / @brian-comply0 status update?

[brian-comply0]

@pjavan hopefully the status is showing for you as in-review. I have one or two items ahead of this in the priority queue. I hope to review it today.

[brian-comply0]

This looks good! Closing.