API Validation and Sanitation

This section describes how API fields are sanitized, and how clients should use/integrate fields in the API to their own use.

Input validation

Numeric and boolean fields

Fields of numeric or boolean type obviously have rather strict input validation, and submitting the wrong data type will result in a 412 error. Numeric fields may also specify a specific range of valid values. Submitting values outside the defined range will also result in a 412 error.

Enum and string fields

String fields with specific values (enums) only allow one of the valid values. Output is guaranteed to only return one of the documented values.

However, note that it is not considered a breaking change to add additional values to the list, so any client should handle “unknown” values (new values added since time of integration) without breaking.

String fields with arbitrary text are typically size limited, and will return 412 error if the submitted value is too long. String fields may also have a “string sanity” policy, specifying which characters are allowed. However, such sanity policy exists to cover business requirements, and should not be considered a security feature.

Warning

Integrating clients should treat text fields as unsafe, and ensure to escape any values before rendering to HTML output or submitting to 3rd party systems (unless these systems do necessary sanitation themselves).

HTML string fields

String fields marked as HTML fields accept HTML, and will typically sanitize the HTML on input (silently discarding disallowed HTML tags). Output HTML fields are marked as “Safe HTML”, meaning that the output is guaranteed to be sanitized by Argus.

Warning

Text fields NOT marked as “Safe HTML” should NOT be trusted, and MUST be sanitized by the client before rendering as HTML

Input validation vs. input sanitation

Normally fields are validated, i.e. will return a 412 error if the value is outside expected range. Fields marked as being “sanitized” will silently be truncated to permitted constraints. This should be explicitly marked in the API documentation.