<commit_before># Assessment

Badges can be issued following assessment of earner applications. Issuers can allow earners to submit applications for badges, forwarding these applications to the API. Reviewers can then assess pending applications, making awarding decisions and submitting their reviews. When a review is submitted, issuers can detect this at their [webhook](webhooks.md). Typically an issuer will respond to an approved review by offering the earner the badge, creating a [badge instance](issuing.md) and marking the application as processed using the updating endpoint below.

Assessment therefore involves two objects in BadgeKit API: applications and reviews.

## Applications

| NAME | VALUE |
|:---|:---|
| `id` | __integer__ - _id from database_ |
| `slug` | __string__ |
| `learner` | __email address__ - _earner email_ |
| `created` | __timestamp__ |
| `assignedTo` | __string__ - _email address for assigned reviewer_ |
| `assignedExpiration` | __timestamp__ - _expiry date for assigned reviewer to complete review, after which another reviewer can be assigned_ |
| `badge` | [badge](badges.md) - _badge applied for_ |
| `processed` | __timestamp__ - _e.g. set when review is submitted or when badge instance is created_ |
| `evidence` | __array__ - _each evidence item can include: `url`, `mediaType` (which can be `image` or `link`) and `reflection` (which is a string)_ |

## Reviews

| NAME | VALUE |
|:---|:---|
| `id` | __integer__ - _id from database_ |
| `slug` | __string__ |
| `author` | __email address__ - _reviewer email_ |
| `comment` | __string__ - _applicant feedback_ |
| `reviewItems` | __array__ - _one for each criteria item in the badge; each reviewItem can include: `criterionId`, `satisfied` status and `comment`_ |
| `approved` | __boolean__ - _indicates success of application_ |

## Endpoints

* [Retrieve Applications](#retrieve-applications)
 * `GET /systems/:slug/applications`
 * `GET /systems/:slug/issuers/:slug/applications`
 * `GET /systems/:slug/issuers/:slug/programs/:slug/applications`
 * `GET /systems/:slug/badges/:slug/applications`
 * `GET /systems/:slug/issuers/:slug/badges/:slug/applications`
 * `GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications`
* [Retrieve a Specific Application](#retrieve-a-specific-application)
 * `GET /systems/:slug/badges/:slug/applications/:slug`
 * `GET /systems/:slug/issuers/:slug/badges/:slug/applications/:slug`
 * `GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug`
* [Submit an Application](#submit-an-application)
 * `POST /systems/:slug/badges/:slug/applications`
 * `POST /systems/:slug/issuers/:slug/badges/:slug/applications`
 * `POST /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications`
* [Update an Application](#update-an-application)
 * `PUT /systems/:slug/badges/:slug/applications/:slug`
 * `PUT /systems/:slug/issuers/:slug/badges/:slug/applications/:slug`
 * `PUT /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug`
* [Delete an Application](#delete-an-application)
 * `DELETE /systems/:slug/badges/:slug/applications/:slug`
 * `DELETE /systems/:slug/issuers/:slug/badges/:slug/applications/:slug`
 * `DELETE /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug`
* [Retrieve Application Reviews](#retrieve-application-reviews)
 * `GET /systems/:slug/badges/:slug/applications/:slug/reviews`
 * `GET /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews`
 * `GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews`
* [Retrieve a Specific Review](#retrieve-a-specific-review)
 * `GET /systems/:slug/badges/:slug/applications/:slug/reviews/:slug`
 * `GET /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug`
 * `GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug`
* [Submit an Application Review](#submit-an-application-review)
 * `POST /systems/:slug/badges/:slug/applications/:slug/reviews`
 * `POST /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews`
 * `POST /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews`
* [Update a Review](#update-a-review)
 * `PUT /systems/:slug/badges/:slug/applications/:slug/reviews/:slug`
 * `PUT /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug`
 * `PUT /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug`
* [Delete a Review](#delete-a-review)
 * `DELETE /systems/:slug/badges/:slug/applications/:slug/reviews/:slug`
 * `DELETE /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug`
 * `DELETE /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug`

## Retrieve Applications

Retrieve existing applications within a system, issuer or program or for a specific badge.

### Expected request

```
GET /systems/:slug/applications
GET /systems/:slug/issuers/:slug/applications
GET /systems/:slug/issuers/:slug/programs/:slug/applications
GET /systems/:slug/badges/:slug/applications
GET /systems/:slug/issuers/:slug/badges/:slug/applications
GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications
```

### Expected response

```
HTTP/1.1 200 OK
Content-Type: application/json
```

```json
{
    "applications": [
        {
            "id": 1,
            "slug": "application-slug",
            "learner": "<EMAIL>",
            "created": "2014-05-29T18:24:59.000Z",
            "assignedTo": null,
            "assignedExpiration": null,
            "badge": {
                ...
            },
            "processed": null,
            "evidence": [
                {
                    "url": null,
                    "mediaType": null,
                    "reflection": "I did things relevant to the badge..."
                },
                {
                    "url": "http://issuersite.com/uploaded-image.jpg",
                    "mediaType": "image",
                    "reflection": "A picture of my evidence."
                },
                {
                    "url": "http://awebsite.com/evidence.html",
                    "mediaType": "link",
                    "reflection": "My website where I did things."
                }
            ]
        },
        ...
    ]
}
```

#### Response structure

* applications `[ ]`
	* id
	* slug
	* learner
	* created
	* assignedTo
	* assignedExpiration
	* [badge](badges.md)
	* processed
	* evidence `[ ]`
		* url
		* mediaType
		* reflection

### Potential errors
<commit_msg>Update assessment.md<commit_after># Assessment

Badges can be issued following assessment of earner applications. Issuers can allow earners to submit applications for badges, forwarding these applications to the API. Reviewers can then assess pending applications, making awarding decisions and submitting their reviews. When a review is submitted, issuers can detect this at their [webhook](webhooks.md). Typically an issuer will respond to an approved review by offering the earner the badge, creating a [badge instance](issuing.md) and marking the application as processed using the updating endpoint below.

Assessment therefore involves two objects in BadgeKit API: applications and reviews.

## Applications

| NAME | VALUE |
|:---|:---|
| `id` | __integer__ - _id from database_ |
| `slug` | __string__ |
| `learner` | __email address__ - _earner email_ |
| `created` | __timestamp__ |
| `assignedTo` | __string__ - _email address for assigned reviewer_ |
| `assignedExpiration` | __timestamp__ - _expiry date for assigned reviewer to complete review, after which another reviewer can be assigned_ |
| `badge` | [badge](badges.md) - _badge applied for_ |
| `processed` | __timestamp__ - _e.g. set when review is submitted or when badge instance is created_ |
| `evidence` | __array__ - _each evidence item can include: `url`, `mediaType` (which can be `image` or `link`) and `reflection` (which is a string)_ |

## Reviews

| NAME | VALUE |
|:---|:---|
| `id` | __integer__ - _id from database_ |
| `slug` | __string__ |
| `author` | __email address__ - _reviewer email_ |
| `comment` | __string__ - _applicant feedback_ |
| `reviewItems` | __array__ - _one for each criteria item in the badge; each reviewItem can include: `criterionId`, `satisfied` status and `comment`_ |
| `approved` | __boolean__ - _indicates success of application_ |

## Endpoints

* [Retrieve Applications](#retrieve-applications)
 * `GET /systems/:slug/applications`
 * `GET /systems/:slug/issuers/:slug/applications`
 * `GET /systems/:slug/issuers/:slug/programs/:slug/applications`
 * `GET /systems/:slug/badges/:slug/applications`
 * `GET /systems/:slug/issuers/:slug/badges/:slug/applications`
 * `GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications`
* [Retrieve a Specific Application](#retrieve-a-specific-application)
 * `GET /systems/:slug/badges/:slug/applications/:slug`
 * `GET /systems/:slug/issuers/:slug/badges/:slug/applications/:slug`
 * `GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug`
* [Submit an Application](#submit-an-application)
 * `POST /systems/:slug/badges/:slug/applications`
 * `POST /systems/:slug/issuers/:slug/badges/:slug/applications`
 * `POST /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications`
* [Update an Application](#update-an-application)
 * `PUT /systems/:slug/badges/:slug/applications/:slug`
 * `PUT /systems/:slug/issuers/:slug/badges/:slug/applications/:slug`
 * `PUT /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug`
* [Delete an Application](#delete-an-application)
 * `DELETE /systems/:slug/badges/:slug/applications/:slug`
 * `DELETE /systems/:slug/issuers/:slug/badges/:slug/applications/:slug`
 * `DELETE /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug`
* [Retrieve Application Reviews](#retrieve-application-reviews)
 * `GET /systems/:slug/badges/:slug/applications/:slug/reviews`
 * `GET /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews`
 * `GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews`
* [Retrieve a Specific Review](#retrieve-a-specific-review)
 * `GET /systems/:slug/badges/:slug/applications/:slug/reviews/:slug`
 * `GET /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug`
 * `GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug`
* [Submit an Application Review](#submit-an-application-review)
 * `POST /systems/:slug/badges/:slug/applications/:slug/reviews`
 * `POST /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews`
 * `POST /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews`
* [Update a Review](#update-a-review)
 * `PUT /systems/:slug/badges/:slug/applications/:slug/reviews/:slug`
 * `PUT /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug`
 * `PUT /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug`
* [Delete a Review](#delete-a-review)
 * `DELETE /systems/:slug/badges/:slug/applications/:slug/reviews/:slug`
 * `DELETE /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug`
 * `DELETE /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug`

## Retrieve Applications

Retrieve existing applications within a system, issuer or program or for a specific badge.

### Expected request

```
GET /systems/:slug/applications
GET /systems/:slug/issuers/:slug/applications
GET /systems/:slug/issuers/:slug/programs/:slug/applications
GET /systems/:slug/badges/:slug/applications
GET /systems/:slug/issuers/:slug/badges/:slug/applications
GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications
```

### Expected response

```
HTTP/1.1 200 OK
Content-Type: application/json
```

```json
{
    "applications": [
        {
            "id": 1,
            "slug": "application-slug",
            "learner": "<EMAIL>",
            "created": "2014-05-29T18:24:59.000Z",
            "assignedTo": null,
            "assignedExpiration": null,
            "badge": {
                ...
            },
            "processed": null,
            "evidence": [
                {
                    "url": null,
                    "mediaType": null,
                    "reflection": "I did things relevant to the badge..."
                },
                {
                    "url": "http://issuersite.com/uploaded-image.jpg",
                    "mediaType": "image",
                    "reflection": "A picture of my evidence."
                },
                {
                    "url": "http://awebsite.com/evidence.html",
                    "mediaType": "link",
                    "reflection": "My website where I did things."
                }
            ]
        },
        ...
    ]
}
```

Applications are returned in order sorted by created date.

#### Response structure

* applications `[ ]`
	* id
	* slug
	* learner
	* created
	* assignedTo
	* assignedExpiration
	* [badge](badges.md)
	* processed
	* evidence `[ ]`
		* url
		* mediaType
		* reflection

### Potential errors

{'fraction_non_alphanumeric': 0.15360336664913204, 'fraction_numerical': 0.0034568272337867287, 'mean_word_length': 3.4242021276595747, 'pattern_counts': {'":': 38, '<': 5, '<?xml version=': 0, '>': 5, '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': '3579089', 'n_tokens_mistral': 4283, 'n_tokens_neox': 4621, 'n_words': 852}