# activities-service client-facing API endpoints

## activities-service MVP endpoints, payload and responses
The following documentation outlines the REST API endpoints for the activities-service, providing information such as the URL format, the payload, and response data structure as well as the relationship of the fields between the endpoints.

All of the endpoints require the `authorization` header containing the same JWT token as used for the backend interaction. activities-service is the focus point to interact regarding new activities, meaning that anything related to the new activities should be directly requested from we-b-cakend, such as the ActivityProgress data creation.

The described endpoints are subject to change once we incorporate changes such as pagination and filtering for multiple activity types.

### **Retrieve Published Resource List**

This endpoint returns a list of published resources compatible with the Activity Lab.

#### Request

GET /api/v0/activity-lab-resources/

No payload

#### Response

- Response Content-Type: application/json
- Expected successful HTTP status code: 200
- Expected failed HTTP status codes: 500

##### Response fields description

The response is **a list of a mapping** containing the following fields:
- `min_quantum`: The minimum quantum value allowed to access this published resource
- `max_quantum`: The maximum quantum value allowed to access this published resource
- `api_version`: The version of the current API response schema
- `title`: The title of the published resource that should be displayed
- `body`: A description of the published resource
- `background_image`: URL of the image that should be displayed as a background
- `id`: Unique UUID of the published resource
- `language`: The language of the content
- `source`: The source where the content was adapted from
- `published`: Boolean value indicating whether the resource was published
- `data_timezone`: The string timezone representation of the timezone-aware timestamps
- `date_published`: The timestamp of when the resource was published
- `tags`: A list of related tags
- `level_name`: The name value of the published resource according to the user scale
- `intro`: An introduction of the published resource that should be displayed
- `media_type`: a string representation of the related media type
- `thumbnail`: URL of the image that should be displayed as a thumbnail
- `practice_url`: URL to access the available activities for the published resource

#### Retrieve Published Resource List Example

##### Request example

GET /api/v0/activity-lab-resources/

No payload

##### Response example

- Response Content-Type: application/json
- HTTP status code: 200
- JSON content:

[
  {
    "min_quantum": 0.029763,
    "max_quantum": 0.125,
    "api_version": "0.0.1",
    "title": "Kayaking in Chicago",
    "body": "A woman paddles a kayak with her dog in Lake Michigan with the skyline of Chicago in the background.",
    "background_image": "https://d10igju90zg67u.cloudfront.net/photologue/photos/cache/e98b9ffcef96bbc42ff2739f921f3f426bc3d854_imgres_preview.jpg",
    "id": "425df747-ecc1-4949-9cd6-3d8dc3c8fe4c",
    "language": "en",
    "source": "Voxy/AP",
    "published": true,
    "data_timezone": "America/Sao_Paulo",
    "date_published": "2021-05-10T16:51:58-03:00",
    "tags": [],
    "level_name": "High Beginner",
    "intro": "A woman paddles a kayak with her dog.",
    "media_type": "image",
    "thumbnail": "https://d10igju90zg67u.cloudfront.net/photologue/photos/cache/e98b9ffcef96bbc42ff2739f921f3f426bc3d854_thumbnail.jpg",
    "practice_url": "/v2/#/activities/lesson/by-resource/425df747-ecc1-4949-9cd6-3d8dc3c8fe4c/"
  }
]

### **Retrieve Activity Data for a Published Resource**

This endpoint returns the activity data for the requested resource.

As we only provide Picture Hunt data for the MVP, the response data for this endpoint is subject to change once we handle for multiple activity types.

#### Request

GET /api/v0/activities/?resource_id=<UUID>

No payload

Required GET parameter:
- `resource_id`: chosen published resource UUID

#### Response

- Response Content-Type: application/json
- Expected successful HTTP status code: 200
- Expected resource not found HTTP status code: 404
- Expected failed HTTP status codes: 400, 500

##### Response fields description

- `activity_id_from_service`: Unique UUID of the generated activity data of the resource
- `type`: The activity type slug of the generated data
- `min_quantum`: The minimum quantum value allowed to access this published resource
- `max_quantum`: The maximum quantum value allowed to access this published resource
- `api_version`: The version of the current API response schema
- `title`: The title of the published resource that should be displayed
- `body`: A description of the published resource
- `background_image`: URL of the image that should be displayed as a background
- `id`: Unique UUID of the published resource
- `language`: The language of the content
- `source`: The source where the content was adapted from
- `published`: Boolean value indicating whether the resource was published
- `data_timezone`: The string timezone representation of the timezone-aware timestamps
- `date_published`: The timestamp of when the resource was published
- `tags`: A list of related tags
- `level_name`: The name value of the published resource according to the user scale
- `intro`: An introduction of the published resource that should be displayed
- `media_type`: a string representation of the related media type
- `thumbnail`: URL of the image that should be displayed as a thumbnail
- `practice_url`: URL to access the available activities for the published resource
- `data`: the specific data for the chosen published resource and activity type

#### Retrieve Activity Data for a Published Resource Example

##### Request example

GET /api/v0/activity-lab-resources/?resource_id=425df747-ecc1-4949-9cd6-3d8dc3c8fe4c

No payload

##### Response example

- Response Content-Type: application/json
- HTTP status code: 200
- JSON content:

{
  "activity_id_from_service": "9323ed06-8237-42a8-8f17-ac41984c12bb",
  "type": "picture-hunt",
  "min_quantum": 0.029763,
  "max_quantum": 0.125,
  "api_version": "0.0.1",
  "title": "Kayaking in Chicago",
  "body": "A woman paddles a kayak with her dog in Lake Michigan with the skyline of Chicago in the background.",
  "background_image": "https://d10igju90zg67u.cloudfront.net/photologue/photos/cache/e98b9ffcef96bbc42ff2739f921f3f426bc3d854_imgres_preview.jpg",
  "id": "425df747-ecc1-4949-9cd6-3d8dc3c8fe4c",
  "language": "en",
  "source": "Voxy/AP",
  "published": true,
  "data_timezone": "America/Sao_Paulo",
  "date_published": "2021-05-10T16:51:58-03:00",
  "tags": [],
  "level_name": "High Beginner",
  "intro": "A woman paddles a kayak with her dog.",
  "media_type": "image",
  "thumbnail": "https://d10igju90zg67u.cloudfront.net/photologue/photos/cache/e98b9ffcef96bbc42ff2739f921f3f426bc3d854_thumbnail.jpg",
  "practice_url": "/v2/#/activities/lesson/by-resource/425df747-ecc1-4949-9cd6-3d8dc3c8fe4c/",
  "data": {
    "base_image": "https://d10igju90zg67u.cloudfront.net/photologue/photos/cache/e98b9ffcef96bbc42ff2739f921f3f426bc3d854_imgres_preview.jpg",
    "challenges": [
      {
        "prompt": "dog",
        "choices": [
          {
            "tts": "https://oxford_media.s3.amazonaws.com/tts_audio/6fb8eadf4a6e3787d280a0c48e265ee5e7d55cae.mp3",
            "definition": "animal with four legs and a tail that many people keep as a pet",
            "hints": [],
            "hotspot": {
              "ul": {
                "x": 0.33166666666666667,
                "y": 0.7016666666666667
              },
              "lr": {
                "x": 0.515,
                "y": 0.87
              }
            }
          }
        ]
      },
      {
        "prompt": "kayak",
        "choices": [
          {
            "tts": "https://s3.amazonaws.com/voxy_media/audio/string/kayak:nn:066c736ded9945cb103e4ed780da633a_1620674475.077353.mp3",
            "definition": "type of a small boat",
            "hints": [],
            "hotspot": {
              "ul": {
                "x": 0.5183333333333333,
                "y": 0.6766666666666666
              },
              "lr": {
                "x": 0.6966666666666667,
                "y": 0.8833333333333333
              }
            }
          }
        ]
      },
      {
        "prompt": "kayak",
        "choices": [
          {
            "tts": "https://s3.amazonaws.com/voxy_media/audio/string/kayak:nn:066c736ded9945cb103e4ed780da633a_1620674475.077353.mp3",
            "definition": "type of a small boat",
            "hints": [],
            "hotspot": {
              "ul": {
                "x": 0.005,
                "y": 0.7583333333333333
              },
              "lr": {
                "x": 0.5716666666666667,
                "y": 0.9466666666666667
              }
            }
          }
        ]
      },
      {
        "prompt": "skyline",
        "choices": [
          {
            "tts": "https://voxy_media.s3.amazonaws.com/tts_audio/7568f34d1e71dec0cf2cb424c0a218e72b4ca948.mp3",
            "definition": "outline of buildings against the sky",
            "hints": [],
            "hotspot": {
              "ul": {
                "x": 0.006666666666666667,
                "y": 0.005
              },
              "lr": {
                "x": 0.9966666666666667,
                "y": 0.4066666666666667
              }
            }
          }
        ]
      },
      {
        "prompt": "lake",
        "choices": [
          {
            "tts": "https://audiostatic.voxy.com/1/1c/1ca/1ca344859e1c7802b60dd651dc5c7dcc4278b75e.mp3",
            "definition": "large area of water that is surrounded by land",
            "hints": [],
            "hotspot": {
              "ul": {
                "x": 0.705,
                "y": 0.41833333333333333
              },
              "lr": {
                "x": 0.9966666666666667,
                "y": 0.995
              }
            }
          }
        ]
      },
      {
        "prompt": "lake",
        "choices": [
          {
            "tts": "https://audiostatic.voxy.com/1/1c/1ca/1ca344859e1c7802b60dd651dc5c7dcc4278b75e.mp3",
            "definition": "large area of water that is surrounded by land",
            "hints": [],
            "hotspot": {
              "ul": {
                "x": 0.005,
                "y": 0.415
              },
              "lr": {
                "x": 0.7033333333333334,
                "y": 0.9916666666666667
              }
            }
          }
        ]
      }
    ]
  }
}

### **Submit Learner Input Data for the Activity Data Interaction for a Published Resource**

This endpoint is used to submit learner input of the activity data interaction for a requested resource.

As we only expect Picture Hunt data, the request payload for this endpoint is expected to allow new data structures once we handle for other activity types.

#### Request

POST /api/v0/activities/

Require payload

##### Request payload fields description

- `activity_id_from_service`: Unique UUID of the generated activity data of the resource - same value as provided in activity data generation response
- `type`: The activity type slug of the generated data
- `seconds_elapsed`: A positive integer representing the total elapsed seconds during the activity
- `resource_from_service`: Unique UUID of the published resource - same value as provided by `id` field in activity data generation response
- `data`: the specific learner input data for the chosen published resource and activity type. In case of Picture Hunt, it is a list of mapping representing how many attempts were required by the learner to find the prompt in the image.

#### Response

- Response Content-Type: application/json
- Expected successful HTTP status code: 201
- Expected failed HTTP status codes: 400, 500

##### Response fields description

- `resource_from_service`: Mutually exclusive value with lesson_progress - unique UUID of the published resource
- `lesson_progress`: Mutually exclusive value with lesson_progress - unique id of the related LessonProgress
- `seconds_elapsed`: A positive integer representing the total elapsed seconds during the activity
- `activity`: The activity type slug of the generated data - same value as provided by `type` in the request payload
- `correct_answers`: A non-negative integer of the number of correct answers
- `total_answers`: A positive integer of the number of total answers
- `word_performance`: A mapping of word performance when the learner activity data yields it
- `id`: Unique id of the ActivityProgress
- `user`: Unique id of the user account in we-b-ackend
- `resource`: A nullable unique id of the legacy non-CTC resouce
- `date_completed`: A nullable timezone representation of the ActivityProgress completion
- `is_complete`: Boolean value indicating whether the ActivityProgress is complete
- `product_section`: A product section slug associated with ActivityProgress

#### Submit Learner Input Data for the Activity Data Interaction for a Published Resource Example

##### Request example

POST /api/v0/activities/

- JSON payload content:

{
  "activity_id_from_service": "9323ed06-8237-42a8-8f17-ac41984c12bb",
  "type": "picture-hunt",
  "seconds_elapsed": 34,
  "resource_from_service": "425df747-ecc1-4949-9cd6-3d8dc3c8fe4c",
  "data": [
    {
      "prompt": "dog",
      "attempts": 1
    },
    {
      "prompt": "kayak",
      "attempts": 3
    },
    {
      "prompt": "skyline",
      "attempts": 5
    },
    {
      "prompt": "lake",
      "attempts": 2
    }
  ]
}

##### Response example

- Response Content-Type: application/json
- HTTP status code: 201
- JSON content:

{
  "resource_from_service": "425df747-ecc1-4949-9cd6-3d8dc3c8fe4c",
  "lesson_progress": null,
  "seconds_elapsed": 34,
  "activity": "picture-hunt",
  "correct_answers": 3,
  "total_answers": 4,
  "word_performance": {},
  "id": 589410160,
  "user": 592881255,
  "resource": null,
  "date_completed": "2022-12-16T19:27:21.309532",
  "is_complete": true,
  "product_section": "standalone_activity"
}