# About this document

All data below should be seen as a draft of the following:

- Which endpoints will be available for Dwarf
- What data can be sent and received through the endpoints

**Table of Contents**

1. Introduction
2. HTTP status codes
3. Endpoints
1. Courses
2. Handball in TV
3. Exercises

Version: **1.0**

# Introduction

This document is intended for SportsSys to verify data and formats, to flag potential issues, to add comments and to potentially extend with further data endpoints that could (or will) be relevant. Most response types are indicated as (example) "team": {team}, to indicate that if there exists a complete type, that type can be returned. If not, a basic string or integer can be returned.

**Links:**

HTTP Status Codes: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

# HTTP status codes

**HTTP codes used for actions:**

- `200` Ok: _Request was successful_
- `201` Created: _Content was created_
- `204` No Content: _Content was deleted_

**HTTP codes used for access checks:**

- `400` Bad Request: _All other user errors than listed below_
- `401` Unauthorized: _Requires authentication_
- `403` Forbidden: _Insufficient permissions_
- `404` Not Found: _Resource not found_
- `405` Method Not Allowed: _Calling an endpoint with a wrong method_
- `409` Conflict: _Resource has changed since last retrieval, causing action to fail_
- `422` Unprocessable Entity: _Validation failed_

# Courses / Kurser

## List

**Description:**

Returns a list of all available courses, including different filters and their options.

If no filters or searchQuery are present, then all courses are returned. The searchQuery can be title, category, type, district or course number.

When a filter is changed, return the updated data and the new filters with their new options.

**Request:**

GET: /courses

**Query Parameters:**

filters:     Array[{FilterName: text, OptionName: int}]
searchQuery: text

**Query Examples**

/courses?filters[courseCategory]=3&filters[courseType]=6

/courses?searchQuery=dommer

**Response:**

{
    "filters": [
        {
            "Id": int,
            "Name": text,
            "FilterOptions": [
                {
                    "Id": int,
                    "Name": text
                },
                ...
            ]        
        },
        ...
    ],
    "data": [
       {
           "Id": int,
           "Category": {CourseCategoryType}
           "Name": text,
           "PublicComment": text,
           "StartDate": date,
           "EndDate": date,
           "Status": text,
           "Stadium": {
               "Shortname": text,
           },
           "MaxParticipants": int,
           "NumberOfParticipants": int,
           "Price": int?,
       },
       ...
    ]
}

**Design examplse**

Filters:

Course data:

## View

**Description:**

Get course by id

**Request:**

GET: /courses/:id

**PATH Parameters:**

id: int

**Response:**

{
	"data": {
           "Id": int,
           "Category": {CourseCategoryType}
           "Name": text,
           "PublicComment": text,
           "StartDate": date,
           "EndDate": date,
           "District": {District},
           "Club": {Club},
           "Stadium": {
               "Shortname": text,
               "Address": {Address}
           },
           "MinParticipants": int,
           "MaxParticipants": int,
           "NumberOfParticipants": int,
           "Instructors": [
               {Person},
               {Person},
               ...
           ]
           "ContactPersons": [
               {Person},
               {Person},
               ...
           ]
           "Price": int,
           "TargetGroup": richtext,
           "LearningObjectives": richtext,
           "Modules": [
               {CourseCourseModule},
               {CourseCourseModule},
               ...
           ]
     }
}

**Design example**
Red text indicates which fields these are mapped to - rest should be self explanatory. TargetGroup and LearningObjective are new richtext fields that don't currently exist. The Modules information is lower down on the page.

# Handball in TV

## List

**Description:**

Paginated list of handball in TV matches. This endpoint should also include "landskampe" in the same format if possible.

**Request:**

GET: /handball-in-tv

**Query Parameters:**

**Response:**

{
    "data": [
       {
           "Id": int,
           "HomeTeam": {
               "Id": int,
               "Name": text,
           },
           "AwayTeam": {
               "Id": int,
               "Name": text
           },
           "Pool": {
               "Id": int,
               "Name": text,
               "Row": {
                   "Id": int,
                   "Name": text
               }
           },
           "Date": date,
           "Time": timespan,
           "TvChannel": {
               "Id": int,
               "Name": text,
               "Url": text
           }
       },
       ...
    ],
}

**Design example:**

# Exercises

## List

**Description:**

Returns a filtered list of exercises

**Request:**

GET: /exercises

**Query Parameters:**

filters:     Array[{FilterName: text, OptionName: int}]
searchQuery: text

**Response:**

{
   "filters": [
        {
            "Id": int,
            "Name": text,
            "FilterOptions": [
                {
                    "Id": int,
                    "Name": text
                },
                ...
            ]        
        },
        ...
    ],
    "data": [
        {
            "id": int,
            "Name": text,
            "Description": text,
            "PublishDate": date,
            "LinkYoutube": text,
            "LinkDHF": text,
            "YoutubeId": text,
            "Category" {
                "Name": text,
                "Sort": int,
                "Pie": text,
                "Description": text,
                "Teaser": text
            }
        }
        ...
    ],
    "meta": {
        "PageSize": int,
        "CurrentPage": int,
        "TotalPages": int,
        "TotalRecords": int,    
    }
}

**Design example:**

## Authors

Andreas Schultz ([e-mail]),
Mads Brodt ([e-mail]),
Thomas Gross Rasmussen ([e-mail])

Last updated: **28/06/2022**