Primary Endpoints

Primary Endpoints interact with the working copy of the OSCAL files themselves.

The following methods apply to every defined OSCAL model.

GET /{model-name}

GET /{model-name} returns a list of accessible content for the specified {model name}. This list is always returned as JSON. Each item in the list includes its content-uuid, which the client can later use for endpoints that require it. The implementation should filter this list to only those items accessible by the asserted identity.

Example

GET /catalog
Returns:

{
   "catalog-list": [
      {
         "content-uuid": "2b51910e-3ffd-432d-92fb-c3ff82a97bd2",
         "title": "First Catalog",
         "published": "2024-09-10T14:00:00Z",
         "version": "1.0",
         "oscal-version": "1.1.2",
         "document-ids": [
            {
               "scheme": "http://oscal.io/oscal/identifier/content-uuid",
               "identifier": "2b51910e-3ffd-432d-92fb-c3ff82a97bd2"
            }
         ],
         "markings": [
            "FOR OFFICIAL USE ONLY  "
         ],
         "remarks": "Optional remarks about this catalog"
      },
      {
         "content-uuid": "cfc31580-33ef-408c-8def-2bfc316222e3",
         "title": "Second Catalog",
         "published": "2024-09-10T14:00:00Z",
         "version": "4.4",
         "oscal-version": "1.1.2",
         "document-ids": [
            {
               "scheme": "http://oscal.io/oscal/identifier/content-uuid",
               "identifier": "cfc31580-33ef-408c-8def-2bfc316222e3"
            }
         ],
         "markings": []
      }
   ]
}

POST /{model-name}

POST /{model-name} directs the implementation to receive valid OSCAL content and store it. Upon receipt the implementation must:

1. check the Content-type header to ensure it specifies the OSCAL format being transmitted. The implementation must only accept application/json, application/xml or application/yaml.
2. ensure the content matches the declared format above and is OSCAL-valid for that format;
3. check for an existing content identifier in the document-ids array (//metaschema/document-ids), as indicated by the scheme value http://oscal.io/oscal/identifier/content-uuid; and
4. store the content.

NOTES:

• If the Content-type header is not present or contains an unrecognized value, the implementation should return an error, but may assume the format is JSON and attempt to continue.
• If the content is not OSCAL-valid to its declared OSCAL version (//metadata/oscal-version), the implementation must return an error, and should include specific validation errors.
• If a content identifier already exists and is a valid v4 or v5 UUID, the implementation must use this as the content-uuid.
• If a content identifier already exists, but is not a valid v4 or v5 UUID, the implementation should either:
  - reject the content as invalid; or
  - correct the error by generating an RFC-4122 compliant v4 or v5 UUID and replacing the invalid identifier.
• If no content identifier is defined in the document-ids, the implementation must generate an RFC-4122 compliant v4 or v5 UUID and insert it into the document-ids array.
• NOTE: RFC-4122 requires only lower-case characters for hex values a through f in UUID values.
• The implementation should enforce access control and only allow content to be submitted when the asserted identity has explicit permission to do so.

GET /{model-name}/{content-uuid}

GET /{model-name}/{content-uuid} directs the implementation to deliver the OSCAL referenced by the content-uuid. content receive valid OSCAL content and store it. Upon receipt of this request, the implementation must:

1. check the Accept header to determine the OSCAL format requested by the client;
2. respond to the request with:
   a. the OSCAL content as the payload; and
   b. the Content-type header to set to either application/json, application/xml or application/yaml.

NOTES:

• The implementation must honor the Accept header as follows. When Accept is set to:
  • application/json or application/oscal+json return the OSCAL content in JSON format;
  • application/xml (preferred by RFC 7303) or text/xml (deprecated by RFC 7303) or application/oscal+xml return the OSCAL content in XML format; or
  • application/yaml or text/yaml return the OSCAL content in YAML format.
• The implementation must set the payload to only include serialized XML, JSON or YAML content that is OSCAL-valid to the client upon receipt with no manipulation.
• The implementation should enforce access control and only return content when the asserted identity has explicit permission to access the content requested.

PUT /{model-name}/{content-uuid}

PUT /{model-name}/{content-uuid} directs the implementation to receive valid OSCAL content and use it to replace existing OSCAL content. Upon receipt the implementation must:

1. check the Content-type header to ensure it specifies the OSCAL format being transmitted. The implementation must only accept application/json, application/xml or application/yaml.
2. ensure the content matches the declared format above and is OSCAL-valid for that format;
3. check for an existing content identifier in the document-ids array (//metaschema/document-ids), as indicated by the scheme value http://oscal.io/oscal/identifier/content-uuid; and
4. replace the prior content with the newly provided content.

NOTES:

• If the Content-type header is not present or contains an unrecognized value, the implementation should return an error, but may assume the format is JSON and attempt to continue.
• If the content is not OSCAL-valid to its declared OSCAL version (//metadata/oscal-version), the implementation must return an error, and should include specific validation errors.
• If a content identifier already exists, is a valid v4 or v5 UUID, but does not match the content-uuid used in the endpoint, the implementation should either:
  • reject the content and raise an error; or
  • allow more than one and honor both.
• If a content identifier already exists, but is not a valid v4 or v5 UUID, the implementation should either:
  • reject the content as invalid; or
  • correct the error by generating an RFC-4122 compliant v4 or v5 UUID and replacing the invalid identifier.
  • NOTE: RFC-4122 requires only lower-case characters for hex values a through f in UUID values.
• The implementation should enforce access control and only allow the replacement of content when the asserted identity has explicit permission to do so.

DELETE /{model-name}/{content-uuid}

DELETE /{model-name}/{content-uuid} directs the implementation to remove the referenced OSCAL content from the local datastore. Upon receipt of this request, the implementation must:

• identify and delete the content itself;
• delete any associated snapshots; and
• delete any associated attachments.

NOTES:

• The implementation may perform the three delete activities (content, snapshot and attachments) in any order it sees fit.
• If the deleted content is subject to record retention policies, litigation holds, or other requirements, the implementation may either:
  • block the delete and return an error; or
  • render the content unavailable via the API, but otherwise retain it as required.
• If the deleted content still exists within system backups, the implementation's owning organization may handle those backups in accordance with organizational requirements.
• If deleted records are retained for any reason, the organization should take reasonable steps to notify the user of retention.
• The implementation should enforce access control and only delete content when the asserted identity has explicit permission to do so.