Overview

1. HTTP verbs

RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

GET

Used to retrieve a resource

POST

Used to create a new resource

PUT

Used to update an existing resource, including partial updates

DELETE

Used to delete an existing resource

2. HTTP status codes

RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

200 OK

The request completed successfully

201 Created

A new resource has been created successfully. The resource’s URI is available from the response’s Location header

204 No Content

An update to an existing resource has been applied successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information

404 Not Found

The requested resource did not exist

3. Headers

Every response has the following header(s):

Name Description

Content-Type

The Content-Type of the payload, e.g. application/hal+json

4. Errors

Whenever an error response (status code >= 400) is returned, the body will contain a JSON object that describes the problem. The error object has the following structure:

Path Type Description

error

String

The HTTP error that occurred, e.g. Bad Request

message

String

A description of the cause of the error

path

String

The path to which the request was made

status

Number

The HTTP status code, e.g. 400

timestamp

String

The time, in milliseconds, at which the error occurred

For example, a request that attempts to apply a non-existent tag to a note will produce a 400 Bad Request response:

HTTP/1.1 400 Bad Request
Content-Type: application/hal+json
Content-Length: 175

{
  "timestamp" : "2024-04-23T12:34:38.569+00:00",
  "status" : 400,
  "error" : "Bad Request",
  "message" : "Bad Request",
  "path" : "/api/v1/competitions/?dateFrom=1023"
}

5. Hypermedia

Zawody Agilife uses hypermedia and resources include links to other resources in their responses. Responses are in Hypertext Application Language (HAL) format. Links can be found beneath the _links key. Users of the API should not create URIs themselves, instead they should use the above-described links to navigate from resource to resource.

5.1. Listing resources

Each request to list resources in a response will return and object containing _embedded field with and object with a collection name of returned resources.

5.1.1. Example

{
  "_embedded" : {
    ...
  },
  "_links" : {
    "first" : {
      "href" : "http://localhost:8080/api/v1/competitions?page=0&size=20"
    },
    "self" : {
      "href" : "http://localhost:8080/api/v1/competitions?page=0&size=20"
    },
    "next" : {
      "href" : "http://localhost:8080/api/v1/competitions?page=1&size=20"
    },
    "last" : {
      "href" : "http://localhost:8080/api/v1/competitions?page=1&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 25,
    "totalPages" : 2,
    "number" : 0
  }
}

Additionally, each request supports paging of the results with following parameters:

5.1.2. Request parameters

Parameter Description

page

Page no. to retrieve

size

Size of a page to retrieve

In there returned result object, there will be included page field with following structure:

Path Type Description

size

Number

No. of returned items per page

totalElements

Number

Total no. of items

totalPages

Number

No. of pages

number

Number

Page no.

For example, a request returning first page of results containing 20 items from 25 items will produce following page object:

5.1.3. Response body page object

{
  "size" : 20,
  "totalElements" : 25,
  "totalPages" : 2,
  "number" : 0
}

Resources

6. Competition

The Competition resource is used to list available resources and retrieve competition details.

6.1. Listing competitions

A GET request is used to access the list of the competitions.

Request may optionally contain paging parameters.

6.1.1. Request parameters

Parameter Description

dateFrom

Return competitions with start date greater or equals

dateTo

Return competitions with end date lower or equal

state

Return only competitions with matching state

6.1.2. HTTP request

GET /api/v1/competitions HTTP/1.1
Content-Type: application/hal+json
Host: localhost:8080

6.1.3. Response fields

Path Type Description

_embedded

Object

Object containing lists

_embedded.competitions

Array

List of competitions

_links

Object

Links to other resources

page

Object

Paging parameters

Fields from object at page field are described in paging fields section.

6.1.4. Example response

HTTP/1.1 200 OK
Content-Type: application/prs.hal-forms+json
Content-Length: 19516

{
  "_embedded" : {
    "competitions" : [ {
      "id" : 3,
      "name" : "Competitions 0",
      "dateFrom" : "2024-04-23",
      "dateTo" : "2024-04-23",
      "details" : null,
      "fees" : null,
      "judges" : [ {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
          }
        }
      } ],
      "state" : "IN_PROGRESS",
      "_links" : {
        "competitions" : {
          "href" : "http://localhost:8080/api/v1/competitions"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitions/3"
        },
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/3/runs"
        }
      }
    }, {
      "id" : 4,
      "name" : "Competitions 1",
      "dateFrom" : "2024-04-23",
      "dateTo" : "2024-04-23",
      "details" : null,
      "fees" : null,
      "judges" : [ {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/4/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/4/nextDogRunsForJudge/3"
          }
        }
      } ],
      "state" : "NEW",
      "_links" : {
        "competitions" : {
          "href" : "http://localhost:8080/api/v1/competitions"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitions/4"
        },
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/4/runs"
        }
      }
    }, {
      "id" : 5,
      "name" : "Competitions 2",
      "dateFrom" : "2024-04-16",
      "dateTo" : "2024-04-16",
      "details" : null,
      "fees" : null,
      "judges" : [ {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/5/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/5/nextDogRunsForJudge/3"
          }
        }
      } ],
      "state" : "NEW",
      "_links" : {
        "competitions" : {
          "href" : "http://localhost:8080/api/v1/competitions"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitions/5"
        },
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/5/runs"
        }
      }
    }, {
      "id" : 6,
      "name" : "Competitions 3",
      "dateFrom" : "2024-04-16",
      "dateTo" : "2024-04-16",
      "details" : null,
      "fees" : null,
      "judges" : [ {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/6/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/6/nextDogRunsForJudge/3"
          }
        }
      } ],
      "state" : "NEW",
      "_links" : {
        "competitions" : {
          "href" : "http://localhost:8080/api/v1/competitions"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitions/6"
        },
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/6/runs"
        }
      }
    }, {
      "id" : 7,
      "name" : "Competitions 4",
      "dateFrom" : "2024-04-09",
      "dateTo" : "2024-04-09",
      "details" : null,
      "fees" : null,
      "judges" : [ {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/7/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/7/nextDogRunsForJudge/3"
          }
        }
      } ],
      "state" : "NEW",
      "_links" : {
        "competitions" : {
          "href" : "http://localhost:8080/api/v1/competitions"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitions/7"
        },
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/7/runs"
        }
      }
    }, {
      "id" : 8,
      "name" : "Competitions 5",
      "dateFrom" : "2024-04-09",
      "dateTo" : "2024-04-09",
      "details" : null,
      "fees" : null,
      "judges" : [ {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/8/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/8/nextDogRunsForJudge/3"
          }
        }
      } ],
      "state" : "NEW",
      "_links" : {
        "competitions" : {
          "href" : "http://localhost:8080/api/v1/competitions"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitions/8"
        },
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/8/runs"
        }
      }
    }, {
      "id" : 9,
      "name" : "Competitions 6",
      "dateFrom" : "2024-04-02",
      "dateTo" : "2024-04-02",
      "details" : null,
      "fees" : null,
      "judges" : [ {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/9/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/9/nextDogRunsForJudge/3"
          }
        }
      } ],
      "state" : "NEW",
      "_links" : {
        "competitions" : {
          "href" : "http://localhost:8080/api/v1/competitions"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitions/9"
        },
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/9/runs"
        }
      }
    }, {
      "id" : 10,
      "name" : "Competitions 7",
      "dateFrom" : "2024-04-02",
      "dateTo" : "2024-04-02",
      "details" : null,
      "fees" : null,
      "judges" : [ {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/10/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/10/nextDogRunsForJudge/3"
          }
        }
      } ],
      "state" : "NEW",
      "_links" : {
        "competitions" : {
          "href" : "http://localhost:8080/api/v1/competitions"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitions/10"
        },
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/10/runs"
        }
      }
    }, {
      "id" : 11,
      "name" : "Competitions 8",
      "dateFrom" : "2024-03-26",
      "dateTo" : "2024-03-26",
      "details" : null,
      "fees" : null,
      "judges" : [ {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/11/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/11/nextDogRunsForJudge/3"
          }
        }
      } ],
      "state" : "NEW",
      "_links" : {
        "competitions" : {
          "href" : "http://localhost:8080/api/v1/competitions"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitions/11"
        },
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/11/runs"
        }
      }
    }, {
      "id" : 12,
      "name" : "Competitions 9",
      "dateFrom" : "2024-03-26",
      "dateTo" : "2024-03-26",
      "details" : null,
      "fees" : null,
      "judges" : [ {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/12/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/12/nextDogRunsForJudge/3"
          }
        }
      } ],
      "state" : "NEW",
      "_links" : {
        "competitions" : {
          "href" : "http://localhost:8080/api/v1/competitions"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitions/12"
        },
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/12/runs"
        }
      }
    }, {
      "id" : 13,
      "name" : "Competitions 10",
      "dateFrom" : "2024-03-19",
      "dateTo" : "2024-03-19",
      "details" : null,
      "fees" : null,
      "judges" : [ {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/13/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/13/nextDogRunsForJudge/3"
          }
        }
      } ],
      "state" : "NEW",
      "_links" : {
        "competitions" : {
          "href" : "http://localhost:8080/api/v1/competitions"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitions/13"
        },
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/13/runs"
        }
      }
    }, {
      "id" : 14,
      "name" : "Competitions 11",
      "dateFrom" : "2024-03-19",
      "dateTo" : "2024-03-19",
      "details" : null,
      "fees" : null,
      "judges" : [ {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/14/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/14/nextDogRunsForJudge/3"
          }
        }
      } ],
      "state" : "NEW",
      "_links" : {
        "competitions" : {
          "href" : "http://localhost:8080/api/v1/competitions"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitions/14"
        },
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/14/runs"
        }
      }
    }, {
      "id" : 15,
      "name" : "Competitions 12",
      "dateFrom" : "2024-03-12",
      "dateTo" : "2024-03-12",
      "details" : null,
      "fees" : null,
      "judges" : [ {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/15/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/15/nextDogRunsForJudge/3"
          }
        }
      } ],
      "state" : "NEW",
      "_links" : {
        "competitions" : {
          "href" : "http://localhost:8080/api/v1/competitions"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitions/15"
        },
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/15/runs"
        }
      }
    }, {
      "id" : 16,
      "name" : "Competitions 13",
      "dateFrom" : "2024-03-12",
      "dateTo" : "2024-03-12",
      "details" : null,
      "fees" : null,
      "judges" : [ {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/16/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/16/nextDogRunsForJudge/3"
          }
        }
      } ],
      "state" : "NEW",
      "_links" : {
        "competitions" : {
          "href" : "http://localhost:8080/api/v1/competitions"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitions/16"
        },
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/16/runs"
        }
      }
    }, {
      "id" : 17,
      "name" : "Competitions 14",
      "dateFrom" : "2024-03-05",
      "dateTo" : "2024-03-05",
      "details" : null,
      "fees" : null,
      "judges" : [ {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/17/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/17/nextDogRunsForJudge/3"
          }
        }
      } ],
      "state" : "NEW",
      "_links" : {
        "competitions" : {
          "href" : "http://localhost:8080/api/v1/competitions"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitions/17"
        },
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/17/runs"
        }
      }
    }, {
      "id" : 18,
      "name" : "Competitions 15",
      "dateFrom" : "2024-03-05",
      "dateTo" : "2024-03-05",
      "details" : null,
      "fees" : null,
      "judges" : [ {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/18/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/18/nextDogRunsForJudge/3"
          }
        }
      } ],
      "state" : "NEW",
      "_links" : {
        "competitions" : {
          "href" : "http://localhost:8080/api/v1/competitions"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitions/18"
        },
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/18/runs"
        }
      }
    }, {
      "id" : 19,
      "name" : "Competitions 16",
      "dateFrom" : "2024-02-27",
      "dateTo" : "2024-02-27",
      "details" : null,
      "fees" : null,
      "judges" : [ {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/19/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/19/nextDogRunsForJudge/3"
          }
        }
      } ],
      "state" : "NEW",
      "_links" : {
        "competitions" : {
          "href" : "http://localhost:8080/api/v1/competitions"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitions/19"
        },
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/19/runs"
        }
      }
    }, {
      "id" : 20,
      "name" : "Competitions 17",
      "dateFrom" : "2024-02-27",
      "dateTo" : "2024-02-27",
      "details" : null,
      "fees" : null,
      "judges" : [ {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/20/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/20/nextDogRunsForJudge/3"
          }
        }
      } ],
      "state" : "NEW",
      "_links" : {
        "competitions" : {
          "href" : "http://localhost:8080/api/v1/competitions"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitions/20"
        },
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/20/runs"
        }
      }
    }, {
      "id" : 21,
      "name" : "Competitions 18",
      "dateFrom" : "2024-02-20",
      "dateTo" : "2024-02-20",
      "details" : null,
      "fees" : null,
      "judges" : [ {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/21/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/21/nextDogRunsForJudge/3"
          }
        }
      } ],
      "state" : "NEW",
      "_links" : {
        "competitions" : {
          "href" : "http://localhost:8080/api/v1/competitions"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitions/21"
        },
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/21/runs"
        }
      }
    }, {
      "id" : 22,
      "name" : "Competitions 19",
      "dateFrom" : "2024-02-20",
      "dateTo" : "2024-02-20",
      "details" : null,
      "fees" : null,
      "judges" : [ {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/22/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/22/nextDogRunsForJudge/3"
          }
        }
      } ],
      "state" : "NEW",
      "_links" : {
        "competitions" : {
          "href" : "http://localhost:8080/api/v1/competitions"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitions/22"
        },
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/22/runs"
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "http://localhost:8080/api/v1/competitions?page=0&size=20"
    },
    "self" : {
      "href" : "http://localhost:8080/api/v1/competitions?page=0&size=20"
    },
    "next" : {
      "href" : "http://localhost:8080/api/v1/competitions?page=1&size=20"
    },
    "last" : {
      "href" : "http://localhost:8080/api/v1/competitions?page=1&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 25,
    "totalPages" : 2,
    "number" : 0
  }
}

6.1.5. Links

Relation Description

self

Current page of list of competitions

first

First page of competitions list

next

Next page of competitions list

last

Last page of competitions list

6.2. Retrieving competition details

A GET request is used to retrieve competition details

6.2.1. Path parameters

Table 1. /api/v1/competitions/{competitionId}
Parameter Description

competitionId

ID of the competition

6.2.2. HTTP request

GET /api/v1/competitions/3 HTTP/1.1
Content-Type: application/hal+json
Host: localhost:8080

6.2.3. Response fields

Path Type Description

id

Number

ID of the competition

name

String

Name of the competition

dateFrom

String

Competitions start date

dateTo

String

Competitions end date

details

Null

Competitions details and description (in Markdown)

fees

Null

Competition fees (in Markdown)

state

String

Competitions state

judges[]

Array

List of judges

_links

Object

Links to other resources
Relation Description

self

This competition

competitions

List of competitions

competitionRuns

List of runs for this competition

6.2.5. Example response

HTTP/1.1 200 OK
Content-Type: application/prs.hal-forms+json
Content-Length: 818

{
  "id" : 3,
  "name" : "Competitions 0",
  "dateFrom" : "2024-04-23",
  "dateTo" : "2024-04-23",
  "details" : null,
  "fees" : null,
  "judges" : [ {
    "id" : 3,
    "firstname" : "Jane",
    "lastname" : "Doe",
    "country" : "PL",
    "_links" : {
      "competitionRuns" : {
        "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
      },
      "nextDogRuns" : {
        "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
      }
    }
  } ],
  "state" : "IN_PROGRESS",
  "_links" : {
    "competitions" : {
      "href" : "http://localhost:8080/api/v1/competitions"
    },
    "self" : {
      "href" : "http://localhost:8080/api/v1/competitions/3"
    },
    "competitionRuns" : {
      "href" : "http://localhost:8080/api/v1/competitions/3/runs"
    }
  }
}

7. Competition level

Resource used to return details about a competition level.

7.1. Response fields

Path Type Description

id

Number

ID of the competition level

name

String

Name of the competition level

8. Competition run

The Competition run resource is used to list available runs for a competition and update them.

8.1. Listing competition runs

A GET request is used to access the list of the competition runs.

Request may optionally contain paging parameters.

8.1.1. Path parameters

Table 2. /api/v1/competitions/{competitionId}/runs
Parameter Description

competitionId

ID of the competition

8.1.2. HTTP request

GET /api/v1/competitions/3/runs HTTP/1.1
Content-Type: application/hal+json
Host: localhost:8080

8.1.3. Response fields

Path Type Description

_embedded

Object

Object containing lists

_embedded.competitionRuns

Array

List of competition runs

_links

Object

Links to other resources

page

Object

Paging parameters

Fields from object at page field are described in paging fields section.

8.1.4. Example response

HTTP/1.1 200 OK
Content-Type: application/prs.hal-forms+json
Content-Length: 24904

{
  "_embedded" : {
    "competitionRuns" : [ {
      "id" : 121,
      "dogSizeClass" : {
        "id" : 9,
        "name" : "S"
      },
      "name" : "Run 0",
      "judge" : {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
          }
        }
      },
      "date" : "2024-04-23",
      "startTime" : "09:00:00",
      "competitionRunLevel" : {
        "id" : 1,
        "name" : "A0"
      },
      "standardTime" : 350.000,
      "maximalTime" : 500.000,
      "trackLength" : 250,
      "progress" : 100,
      "_links" : {
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/3/runs"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitionRuns/121"
        },
        "dogRuns" : {
          "href" : "http://localhost:8080/api/v1/dogRuns/121"
        },
        "competition" : {
          "href" : "http://localhost:8080/api/v1/competitions/3"
        }
      }
    }, {
      "id" : 122,
      "dogSizeClass" : {
        "id" : 9,
        "name" : "S"
      },
      "name" : "Run 1",
      "judge" : {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
          }
        }
      },
      "date" : "2024-04-23",
      "startTime" : "09:30:00",
      "competitionRunLevel" : {
        "id" : 2,
        "name" : "A1"
      },
      "standardTime" : 120.000,
      "maximalTime" : 200.000,
      "trackLength" : 250,
      "progress" : 100,
      "_links" : {
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/3/runs"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitionRuns/122"
        },
        "dogRuns" : {
          "href" : "http://localhost:8080/api/v1/dogRuns/122"
        },
        "competition" : {
          "href" : "http://localhost:8080/api/v1/competitions/3"
        }
      }
    }, {
      "id" : 123,
      "dogSizeClass" : {
        "id" : 9,
        "name" : "S"
      },
      "name" : "Run 2",
      "judge" : {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
          }
        }
      },
      "date" : "2024-04-23",
      "startTime" : "10:00:00",
      "competitionRunLevel" : {
        "id" : 3,
        "name" : "A2"
      },
      "standardTime" : 120.000,
      "maximalTime" : 200.000,
      "trackLength" : 250,
      "progress" : 100,
      "_links" : {
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/3/runs"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitionRuns/123"
        },
        "dogRuns" : {
          "href" : "http://localhost:8080/api/v1/dogRuns/123"
        },
        "competition" : {
          "href" : "http://localhost:8080/api/v1/competitions/3"
        }
      }
    }, {
      "id" : 124,
      "dogSizeClass" : {
        "id" : 9,
        "name" : "S"
      },
      "name" : "Run 3",
      "judge" : {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
          }
        }
      },
      "date" : "2024-04-23",
      "startTime" : "10:30:00",
      "competitionRunLevel" : {
        "id" : 4,
        "name" : "A3"
      },
      "standardTime" : 120.000,
      "maximalTime" : 200.000,
      "trackLength" : 250,
      "progress" : 100,
      "_links" : {
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/3/runs"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitionRuns/124"
        },
        "dogRuns" : {
          "href" : "http://localhost:8080/api/v1/dogRuns/124"
        },
        "competition" : {
          "href" : "http://localhost:8080/api/v1/competitions/3"
        }
      }
    }, {
      "id" : 125,
      "dogSizeClass" : {
        "id" : 9,
        "name" : "S"
      },
      "name" : "Run 4",
      "judge" : {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
          }
        }
      },
      "date" : "2024-04-23",
      "startTime" : "11:00:00",
      "competitionRunLevel" : {
        "id" : 5,
        "name" : "Open"
      },
      "standardTime" : 120.000,
      "maximalTime" : 200.000,
      "trackLength" : 250,
      "progress" : 100,
      "_links" : {
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/3/runs"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitionRuns/125"
        },
        "dogRuns" : {
          "href" : "http://localhost:8080/api/v1/dogRuns/125"
        },
        "competition" : {
          "href" : "http://localhost:8080/api/v1/competitions/3"
        }
      }
    }, {
      "id" : 126,
      "dogSizeClass" : {
        "id" : 10,
        "name" : "M"
      },
      "name" : "Run 5",
      "judge" : {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
          }
        }
      },
      "date" : "2024-04-23",
      "startTime" : "11:30:00",
      "competitionRunLevel" : {
        "id" : 1,
        "name" : "A0"
      },
      "standardTime" : 120.000,
      "maximalTime" : 200.000,
      "trackLength" : 250,
      "progress" : 100,
      "_links" : {
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/3/runs"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitionRuns/126"
        },
        "dogRuns" : {
          "href" : "http://localhost:8080/api/v1/dogRuns/126"
        },
        "competition" : {
          "href" : "http://localhost:8080/api/v1/competitions/3"
        }
      }
    }, {
      "id" : 127,
      "dogSizeClass" : {
        "id" : 10,
        "name" : "M"
      },
      "name" : "Run 6",
      "judge" : {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
          }
        }
      },
      "date" : "2024-04-23",
      "startTime" : "12:00:00",
      "competitionRunLevel" : {
        "id" : 2,
        "name" : "A1"
      },
      "standardTime" : 120.000,
      "maximalTime" : 200.000,
      "trackLength" : 250,
      "progress" : 100,
      "_links" : {
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/3/runs"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitionRuns/127"
        },
        "dogRuns" : {
          "href" : "http://localhost:8080/api/v1/dogRuns/127"
        },
        "competition" : {
          "href" : "http://localhost:8080/api/v1/competitions/3"
        }
      }
    }, {
      "id" : 128,
      "dogSizeClass" : {
        "id" : 10,
        "name" : "M"
      },
      "name" : "Run 7",
      "judge" : {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
          }
        }
      },
      "date" : "2024-04-23",
      "startTime" : "12:30:00",
      "competitionRunLevel" : {
        "id" : 3,
        "name" : "A2"
      },
      "standardTime" : 350.000,
      "maximalTime" : 500.000,
      "trackLength" : 250,
      "progress" : 20,
      "_links" : {
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/3/runs"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitionRuns/128"
        },
        "dogRuns" : {
          "href" : "http://localhost:8080/api/v1/dogRuns/128"
        },
        "competition" : {
          "href" : "http://localhost:8080/api/v1/competitions/3"
        }
      }
    }, {
      "id" : 129,
      "dogSizeClass" : {
        "id" : 10,
        "name" : "M"
      },
      "name" : "Run 8",
      "judge" : {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
          }
        }
      },
      "date" : "2024-04-23",
      "startTime" : "13:00:00",
      "competitionRunLevel" : {
        "id" : 4,
        "name" : "A3"
      },
      "standardTime" : 120.000,
      "maximalTime" : 200.000,
      "trackLength" : 250,
      "progress" : 100,
      "_links" : {
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/3/runs"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitionRuns/129"
        },
        "dogRuns" : {
          "href" : "http://localhost:8080/api/v1/dogRuns/129"
        },
        "competition" : {
          "href" : "http://localhost:8080/api/v1/competitions/3"
        }
      }
    }, {
      "id" : 130,
      "dogSizeClass" : {
        "id" : 10,
        "name" : "M"
      },
      "name" : "Run 9",
      "judge" : {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
          }
        }
      },
      "date" : "2024-04-23",
      "startTime" : "13:30:00",
      "competitionRunLevel" : {
        "id" : 5,
        "name" : "Open"
      },
      "standardTime" : 120.000,
      "maximalTime" : 200.000,
      "trackLength" : 250,
      "progress" : 0,
      "_links" : {
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/3/runs"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitionRuns/130"
        },
        "dogRuns" : {
          "href" : "http://localhost:8080/api/v1/dogRuns/130"
        },
        "competition" : {
          "href" : "http://localhost:8080/api/v1/competitions/3"
        }
      }
    }, {
      "id" : 131,
      "dogSizeClass" : {
        "id" : 11,
        "name" : "I"
      },
      "name" : "Run 10",
      "judge" : {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
          }
        }
      },
      "date" : "2024-04-23",
      "startTime" : "14:00:00",
      "competitionRunLevel" : {
        "id" : 1,
        "name" : "A0"
      },
      "standardTime" : 120.000,
      "maximalTime" : 200.000,
      "trackLength" : 250,
      "progress" : 100,
      "_links" : {
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/3/runs"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitionRuns/131"
        },
        "dogRuns" : {
          "href" : "http://localhost:8080/api/v1/dogRuns/131"
        },
        "competition" : {
          "href" : "http://localhost:8080/api/v1/competitions/3"
        }
      }
    }, {
      "id" : 132,
      "dogSizeClass" : {
        "id" : 11,
        "name" : "I"
      },
      "name" : "Run 11",
      "judge" : {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
          }
        }
      },
      "date" : "2024-04-23",
      "startTime" : "14:30:00",
      "competitionRunLevel" : {
        "id" : 2,
        "name" : "A1"
      },
      "standardTime" : 120.000,
      "maximalTime" : 200.000,
      "trackLength" : 250,
      "progress" : 100,
      "_links" : {
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/3/runs"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitionRuns/132"
        },
        "dogRuns" : {
          "href" : "http://localhost:8080/api/v1/dogRuns/132"
        },
        "competition" : {
          "href" : "http://localhost:8080/api/v1/competitions/3"
        }
      }
    }, {
      "id" : 133,
      "dogSizeClass" : {
        "id" : 11,
        "name" : "I"
      },
      "name" : "Run 12",
      "judge" : {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
          }
        }
      },
      "date" : "2024-04-23",
      "startTime" : "15:00:00",
      "competitionRunLevel" : {
        "id" : 3,
        "name" : "A2"
      },
      "standardTime" : 120.000,
      "maximalTime" : 200.000,
      "trackLength" : 250,
      "progress" : 100,
      "_links" : {
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/3/runs"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitionRuns/133"
        },
        "dogRuns" : {
          "href" : "http://localhost:8080/api/v1/dogRuns/133"
        },
        "competition" : {
          "href" : "http://localhost:8080/api/v1/competitions/3"
        }
      }
    }, {
      "id" : 134,
      "dogSizeClass" : {
        "id" : 11,
        "name" : "I"
      },
      "name" : "Run 13",
      "judge" : {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
          }
        }
      },
      "date" : "2024-04-23",
      "startTime" : "15:30:00",
      "competitionRunLevel" : {
        "id" : 4,
        "name" : "A3"
      },
      "standardTime" : 120.000,
      "maximalTime" : 200.000,
      "trackLength" : 250,
      "progress" : 100,
      "_links" : {
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/3/runs"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitionRuns/134"
        },
        "dogRuns" : {
          "href" : "http://localhost:8080/api/v1/dogRuns/134"
        },
        "competition" : {
          "href" : "http://localhost:8080/api/v1/competitions/3"
        }
      }
    }, {
      "id" : 135,
      "dogSizeClass" : {
        "id" : 11,
        "name" : "I"
      },
      "name" : "Run 14",
      "judge" : {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
          }
        }
      },
      "date" : "2024-04-23",
      "startTime" : "16:00:00",
      "competitionRunLevel" : {
        "id" : 5,
        "name" : "Open"
      },
      "standardTime" : 120.000,
      "maximalTime" : 200.000,
      "trackLength" : 250,
      "progress" : 100,
      "_links" : {
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/3/runs"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitionRuns/135"
        },
        "dogRuns" : {
          "href" : "http://localhost:8080/api/v1/dogRuns/135"
        },
        "competition" : {
          "href" : "http://localhost:8080/api/v1/competitions/3"
        }
      }
    }, {
      "id" : 136,
      "dogSizeClass" : {
        "id" : 12,
        "name" : "L"
      },
      "name" : "Run 15",
      "judge" : {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
          }
        }
      },
      "date" : "2024-04-23",
      "startTime" : "16:30:00",
      "competitionRunLevel" : {
        "id" : 1,
        "name" : "A0"
      },
      "standardTime" : 120.000,
      "maximalTime" : 200.000,
      "trackLength" : 250,
      "progress" : 100,
      "_links" : {
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/3/runs"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitionRuns/136"
        },
        "dogRuns" : {
          "href" : "http://localhost:8080/api/v1/dogRuns/136"
        },
        "competition" : {
          "href" : "http://localhost:8080/api/v1/competitions/3"
        }
      }
    }, {
      "id" : 137,
      "dogSizeClass" : {
        "id" : 12,
        "name" : "L"
      },
      "name" : "Run 16",
      "judge" : {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
          }
        }
      },
      "date" : "2024-04-23",
      "startTime" : "17:00:00",
      "competitionRunLevel" : {
        "id" : 2,
        "name" : "A1"
      },
      "standardTime" : 120.000,
      "maximalTime" : 200.000,
      "trackLength" : 250,
      "progress" : 100,
      "_links" : {
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/3/runs"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitionRuns/137"
        },
        "dogRuns" : {
          "href" : "http://localhost:8080/api/v1/dogRuns/137"
        },
        "competition" : {
          "href" : "http://localhost:8080/api/v1/competitions/3"
        }
      }
    }, {
      "id" : 138,
      "dogSizeClass" : {
        "id" : 12,
        "name" : "L"
      },
      "name" : "Run 17",
      "judge" : {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
          }
        }
      },
      "date" : "2024-04-23",
      "startTime" : "17:30:00",
      "competitionRunLevel" : {
        "id" : 3,
        "name" : "A2"
      },
      "standardTime" : 120.000,
      "maximalTime" : 200.000,
      "trackLength" : 250,
      "progress" : 100,
      "_links" : {
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/3/runs"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitionRuns/138"
        },
        "dogRuns" : {
          "href" : "http://localhost:8080/api/v1/dogRuns/138"
        },
        "competition" : {
          "href" : "http://localhost:8080/api/v1/competitions/3"
        }
      }
    }, {
      "id" : 139,
      "dogSizeClass" : {
        "id" : 12,
        "name" : "L"
      },
      "name" : "Run 18",
      "judge" : {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
          }
        }
      },
      "date" : "2024-04-23",
      "startTime" : "18:00:00",
      "competitionRunLevel" : {
        "id" : 4,
        "name" : "A3"
      },
      "standardTime" : 120.000,
      "maximalTime" : 200.000,
      "trackLength" : 250,
      "progress" : 100,
      "_links" : {
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/3/runs"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitionRuns/139"
        },
        "dogRuns" : {
          "href" : "http://localhost:8080/api/v1/dogRuns/139"
        },
        "competition" : {
          "href" : "http://localhost:8080/api/v1/competitions/3"
        }
      }
    }, {
      "id" : 140,
      "dogSizeClass" : {
        "id" : 12,
        "name" : "L"
      },
      "name" : "Run 19",
      "judge" : {
        "id" : 3,
        "firstname" : "Jane",
        "lastname" : "Doe",
        "country" : "PL",
        "_links" : {
          "competitionRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
          },
          "nextDogRuns" : {
            "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
          }
        }
      },
      "date" : "2024-04-23",
      "startTime" : "18:30:00",
      "competitionRunLevel" : {
        "id" : 5,
        "name" : "Open"
      },
      "standardTime" : 120.000,
      "maximalTime" : 200.000,
      "trackLength" : 250,
      "progress" : 100,
      "_links" : {
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/3/runs"
        },
        "self" : {
          "href" : "http://localhost:8080/api/v1/competitionRuns/140"
        },
        "dogRuns" : {
          "href" : "http://localhost:8080/api/v1/dogRuns/140"
        },
        "competition" : {
          "href" : "http://localhost:8080/api/v1/competitions/3"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/v1/competitions/3/runs?page=0&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 20,
    "totalPages" : 1,
    "number" : 0
  }
}

8.1.5. Links

Relation Description

self

This competition runs list

first

First page of competition runs list

next

Next page of competition runs list

last

Last page of competition runs list

8.2. Retrieving competition run details

A GET request is used to retrieve competition run details

8.2.1. Path parameters

Table 3. /api/v1/competitionRuns/{runId}
Parameter Description

runId

ID of the competition run

8.2.2. HTTP request

GET /api/v1/competitionRuns/121 HTTP/1.1
Content-Type: application/hal+json
Host: localhost:8080

8.2.3. Response fields

Path Type Description

id

Number

ID of the competition run

name

String

Name of the competition run

date

String

Date of the run

startTime

String

Time when run starts

standardTime

Number

Standard time in seconds

maximalTime

Number

Maximal time in seconds

trackLength

Number

Length of a track in seconds

progress

Number

Percents of completed dog runs for this competition run

dogSizeClass

Object

Dog size class

competitionRunLevel

Object

Competition run level

judge

Object

Judge of the run

_links

Object

Links to other resources
Relation Description

self

This competition

competition

Competition which contains this run

competitionRuns

List of runs for the same competition

dogRuns

List of dog runs for this competition run

8.2.5. Example response

HTTP/1.1 200 OK
Content-Type: application/prs.hal-forms+json
Content-Length: 1048

{
  "id" : 121,
  "dogSizeClass" : {
    "id" : 9,
    "name" : "S"
  },
  "name" : "Run 0",
  "judge" : {
    "id" : 3,
    "firstname" : "Jane",
    "lastname" : "Doe",
    "country" : "PL",
    "_links" : {
      "competitionRuns" : {
        "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
      },
      "nextDogRuns" : {
        "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
      }
    }
  },
  "date" : "2024-04-23",
  "startTime" : "09:00:00",
  "competitionRunLevel" : {
    "id" : 1,
    "name" : "A0"
  },
  "standardTime" : 120.000,
  "maximalTime" : 200.000,
  "trackLength" : 250,
  "progress" : 100,
  "_links" : {
    "competitionRuns" : {
      "href" : "http://localhost:8080/api/v1/competitions/3/runs"
    },
    "self" : {
      "href" : "http://localhost:8080/api/v1/competitionRuns/121"
    },
    "dogRuns" : {
      "href" : "http://localhost:8080/api/v1/dogRuns/121"
    },
    "competition" : {
      "href" : "http://localhost:8080/api/v1/competitions/3"
    }
  }
}

8.3. Update competition run details

A PUT request is used to update competition run details.

8.3.1. Path parameters

Table 4. /api/v1/competitionRuns/{runId}
Parameter Description

runId

ID of the competition run

8.3.2. Request fields

Path Type Description

trackLength

Number

Length of the track

maximalTime

Number

Maximal time

standardTime

Number

Standard time

8.3.3. HTTP request

PUT /api/v1/competitionRuns/121 HTTP/1.1
Content-Type: application/hal+json
Content-Length: 76
Host: localhost:8080

{
  "trackLength" : 250,
  "standardTime" : 350.0,
  "maximalTime" : 500.0
}

8.3.4. Response fields

In the response, server returns updated competition run details (the same as in GET request).

8.3.5. Example response

HTTP/1.1 200 OK
Content-Type: application/prs.hal-forms+json
Content-Length: 1044

{
  "id" : 121,
  "dogSizeClass" : {
    "id" : 9,
    "name" : "S"
  },
  "name" : "Run 0",
  "judge" : {
    "id" : 3,
    "firstname" : "Jane",
    "lastname" : "Doe",
    "country" : "PL",
    "_links" : {
      "competitionRuns" : {
        "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
      },
      "nextDogRuns" : {
        "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
      }
    }
  },
  "date" : "2024-04-23",
  "startTime" : "09:00:00",
  "competitionRunLevel" : {
    "id" : 1,
    "name" : "A0"
  },
  "standardTime" : 350.0,
  "maximalTime" : 500.0,
  "trackLength" : 250,
  "progress" : 100,
  "_links" : {
    "competitionRuns" : {
      "href" : "http://localhost:8080/api/v1/competitions/3/runs"
    },
    "self" : {
      "href" : "http://localhost:8080/api/v1/competitionRuns/121"
    },
    "dogRuns" : {
      "href" : "http://localhost:8080/api/v1/dogRuns/121"
    },
    "competition" : {
      "href" : "http://localhost:8080/api/v1/competitions/3"
    }
  }
}

9. Competition run level

Resource used to return details about competition run level.

9.1. Response fields

Path Type Description

id

Number

ID of the competition run level

name

String

Name of the competition run level

10. Competitor

Resource used to return details about a competitor.

10.1. Response fields

Path Type Description

id

Number

ID of the competitor

firstname

String

First name of the competitor

lastname

String

Last name of the competitor

identifier

String

Identifier

country

String

Country code of the competitor

11. Dog

Resource used to return details about a dog.

11.1. Response fields

Path Type Description

id

Number

ID of the dog

name

String

Name of the dog

homeName

String

Home name of the dog

workbookNo

String

No. of the workbook

birthday

String

Birthday

competitionLevel

Object

Competition level of the dog

dogSizeClass

Object

Dog size class

12. Dog run

The Dog run resource is used to list available dog runs for a competition run and update them.

12.1. Listing dog runs

A GET request is used to access the list of the dog runs.

Request may optionally contain paging parameters.

12.1.1. Path parameters

Table 5. /api/v1/competitionRuns/{runId}/dogRuns
Parameter Description

runId

ID of the competition run

12.1.2. HTTP request

GET /api/v1/competitionRuns/121/dogRuns HTTP/1.1
Content-Type: application/hal+json
Host: localhost:8080

12.1.3. Response fields

Path Type Description

_embedded

Object

Object containing lists

_embedded.dogRuns

Array

List of dog runs

_links

Object

Links to other resources

page

Object

Paging parameters

Fields from object at page field are described in paging fields section.

12.1.4. Example response

HTTP/1.1 200 OK
Content-Type: application/prs.hal-forms+json
Content-Length: 231

{
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/v1/competitionRuns/121/dogRuns?page=0&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 0,
    "totalPages" : 0,
    "number" : 0
  }
}

12.1.5. Links

Relation Description

self

This dog runs list

first

First page of dog runs list

next

Next page of dog runs list

last

Last page of dog runs list

12.2. Retrieving dog run details

A GET request is used to retrieve dog run details

12.2.1. Path parameters

Table 6. /api/v1/dogRuns/{runId}
Parameter Description

runId

ID of the dog run

12.2.2. HTTP request

GET /api/v1/dogRuns/20 HTTP/1.1
Content-Type: application/hal+json
Host: localhost:8080

12.2.3. Response fields

Path Type Description

id

Number

ID of the dog run

time

Number

Measured of the dog run

refusals

Number

No. of refusals

faults

Number

No. of faults

disqualified

Boolean

true if participant was disqualified

absence

Boolean

true if participant was absent(didn’t run)

competitionRun

Object

Competition run to which this dog run belongs

dog

Object

Dog

competitor

Object

Competitor

_links

Object

Links to other resources
Relation Description

self

This dog run

competitionRun

Competition run to which this dog run belongs

competition

Competition which contains this dog run>>

12.2.5. Example response

HTTP/1.1 200 OK
Content-Type: application/prs.hal-forms+json
Content-Length: 1986

{
  "id" : 20,
  "dog" : {
    "id" : 5,
    "name" : "Charlie",
    "homeName" : "Charlie",
    "workbookNo" : "2020/x/0",
    "competitionLevel" : {
      "id" : 3,
      "name" : "A2"
    },
    "birthday" : "2021-04-23",
    "dogSizeClass" : {
      "id" : 10,
      "name" : "M"
    }
  },
  "competitionRun" : {
    "id" : 128,
    "dogSizeClass" : {
      "id" : 10,
      "name" : "M"
    },
    "name" : "Run 7",
    "judge" : {
      "id" : 3,
      "firstname" : "Jane",
      "lastname" : "Doe",
      "country" : "PL",
      "_links" : {
        "competitionRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
        },
        "nextDogRuns" : {
          "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
        }
      }
    },
    "date" : "2024-04-23",
    "startTime" : "12:30:00",
    "competitionRunLevel" : {
      "id" : 3,
      "name" : "A2"
    },
    "standardTime" : 120.000,
    "maximalTime" : 200.000,
    "trackLength" : 250,
    "progress" : 0,
    "_links" : {
      "competitionRuns" : {
        "href" : "http://localhost:8080/api/v1/competitions/3/runs"
      },
      "self" : {
        "href" : "http://localhost:8080/api/v1/competitionRuns/128"
      },
      "dogRuns" : {
        "href" : "http://localhost:8080/api/v1/dogRuns/128"
      },
      "competition" : {
        "href" : "http://localhost:8080/api/v1/competitions/3"
      }
    }
  },
  "competitor" : {
    "id" : 9,
    "firstname" : "John 0",
    "lastname" : "Doe",
    "identifier" : "2018/088123/0",
    "country" : null
  },
  "time" : null,
  "refusals" : 0,
  "faults" : 0,
  "disqualified" : false,
  "absence" : false,
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/v1/dogRuns/20"
    },
    "competitionRun" : {
      "href" : "http://localhost:8080/api/v1/competitionRuns/128"
    },
    "competition" : {
      "href" : "http://localhost:8080/api/v1/competitions/3"
    }
  }
}

12.3. Update dog run details

A PUT request is used to update dog run details.

12.3.1. Path parameters

Table 7. /api/v1/dogRuns/{runId}
Parameter Description

runId

ID of the dog run

12.3.2. Request fields

Path Type Description

time

Number

Measured dog run time

refusals

Number

No. of refusals

faults

Number

No. of faults

disqualified

Boolean

true if participant was disqualified

absence

Boolean

true if participant was absent (didn’t run)

12.3.3. HTTP request

PUT /api/v1/dogRuns/20 HTTP/1.1
Content-Type: application/hal+json
Content-Length: 103
Host: localhost:8080

{
  "disqualified" : false,
  "absence" : false,
  "refusals" : 1,
  "time" : 180.236,
  "faults" : 0
}

12.3.4. Response fields

In the response, server returns updated dog run details (the same as in GET request).

12.3.5. Example response

HTTP/1.1 200 OK
Content-Type: application/prs.hal-forms+json
Content-Length: 1044

{
  "id" : 121,
  "dogSizeClass" : {
    "id" : 9,
    "name" : "S"
  },
  "name" : "Run 0",
  "judge" : {
    "id" : 3,
    "firstname" : "Jane",
    "lastname" : "Doe",
    "country" : "PL",
    "_links" : {
      "competitionRuns" : {
        "href" : "http://localhost:8080/api/v1/competitions/3/runs?judgeId=3"
      },
      "nextDogRuns" : {
        "href" : "http://localhost:8080/api/v1/competitions/3/nextDogRunsForJudge/3"
      }
    }
  },
  "date" : "2024-04-23",
  "startTime" : "09:00:00",
  "competitionRunLevel" : {
    "id" : 1,
    "name" : "A0"
  },
  "standardTime" : 350.0,
  "maximalTime" : 500.0,
  "trackLength" : 250,
  "progress" : 100,
  "_links" : {
    "competitionRuns" : {
      "href" : "http://localhost:8080/api/v1/competitions/3/runs"
    },
    "self" : {
      "href" : "http://localhost:8080/api/v1/competitionRuns/121"
    },
    "dogRuns" : {
      "href" : "http://localhost:8080/api/v1/dogRuns/121"
    },
    "competition" : {
      "href" : "http://localhost:8080/api/v1/competitions/3"
    }
  }
}

13. Dog size class

Resource used to return details about dog size class.

13.1. Response fields

Path Type Description

id

Number

ID of the dog size class

name

String

Name of the dog size class

14. Judge

Resource used to return details about judge.

14.1. Response fields

Path Type Description

id

Number

ID of the entry

firstname

String

First name of the judge

lastname

String

Last name of the judge

country

String

Two letter code of judge nationality

14.2. Links

Relation Description

competitionRuns

List of competitions runs judge by this person in context of this competition

nextDogRuns

Next dog runs judged by this person in context of this competition