<commit_before>This file documents the HaaS REST API in detail.

# How to read

Each possible API call has an entry below containing:

* an HTTP method and URL path, including possible `<parameters>` in the
  path to be treated as arguments.
* Optionally, a summary of the request body (which will always be a JSON
  object).
* A human readable description of the semantics of the call
* A summary of the response body for a successful request. Many calls do
  not return any data, in which case this is omitted.
* A description of the requirements for an authorized call. This will be
  combination of:
  * Administrative access
  * Access to project `<project name>`
  * No special access.
 In general, administrative access is sufficient to perform any action.
* A list of possible errors.

In addition to the error codes listed for each API call, HaaS may
return:

* 400 if something is wrong with the request (e.g. malformed request
  body)
* 401 if the user does not have permission to execute the supplied
  request.
* 404 if the api call references an object that does not exist
  (obviously, this is acceptable for calls that create the resource).
  This may also be returned in cases where a user does not have
  permission to access a resource, in order to avoid leaking the fact
  that the resource does in fact exist.

Below is an example.

## my_api_call

`POST /url/path/to/<thing>`

Request Body:

    {
        "some_field": "a value",
        "this-is-an-example": true,
        "some-optional-field": { (Optional)
            "more-fields": 12352356,
            ...
        }
    }

Attempt to do something mysterious to `<thing>` which must be a coffee
pot, and must not be in use by other users. If successful, the response
will include some cryptic information.

Response Body (on success):

    {
        "some-info": "Hello, World!",<commit_msg>docs/rest_api: Remove stuff re: 404s to avoid info leaks.<commit_after>This file documents the HaaS REST API in detail.

# How to read

Each possible API call has an entry below containing:

* an HTTP method and URL path, including possible `<parameters>` in the
  path to be treated as arguments.
* Optionally, a summary of the request body (which will always be a JSON
  object).
* A human readable description of the semantics of the call
* A summary of the response body for a successful request. Many calls do
  not return any data, in which case this is omitted.
* A description of the requirements for an authorized call. This will be
  combination of:
  * Administrative access
  * Access to project `<project name>`
  * No special access.
 In general, administrative access is sufficient to perform any action.
* A list of possible errors.

In addition to the error codes listed for each API call, HaaS may
return:

* 400 if something is wrong with the request (e.g. malformed request
  body)
* 401 if the user does not have permission to execute the supplied
  request.
* 404 if the api call references an object that does not exist
  (obviously, this is acceptable for calls that create the resource).

Below is an example.

## my_api_call

`POST /url/path/to/<thing>`

Request Body:

    {
        "some_field": "a value",
        "this-is-an-example": true,
        "some-optional-field": { (Optional)
            "more-fields": 12352356,
            ...
        }
    }

Attempt to do something mysterious to `<thing>` which must be a coffee
pot, and must not be in use by other users. If successful, the response
will include some cryptic information.

Response Body (on success):

    {
        "some-info": "Hello, World!",
{'fraction_non_alphanumeric': 0.0664819944598338, 'fraction_numerical': 0.010249307479224376, 'mean_word_length': 3.248235294117647, 'pattern_counts': {'":': 10, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2174578', 'n_tokens_mistral': 1011, 'n_tokens_neox': 951, 'n_words': 521}